A Quickshell-based wallpaper selector for Wayland compositors.

• Local and remote (Wallhaven) wallpaper support
• Dual view modes: CoverFlow carousel & grid view
• Search, filter, and browse wallpapers by folder
• Concurrent thumbnail generation with ffmpeg
• Wallhaven API integration with download/apply
• Folder picker for wallpaper and cache directories
• Full keyboard navigation

• awww - Wallpaper daemon with transitions
• wlr-randr - Monitor detection
• Quickshell - QML-based Wayland shell
• ffmpeg - Thumbnail generation
• imagemagick - Dynamic logo color extraction

• mpvpaper - Video wallpaper support
• curl - Wallhaven API requests and wallpaper downloads

sudo pacman -S awww wlr-randr quickshell ffmpeg imagemagick mpvpaper curl

Add to your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    npaper.url = "github:lonerOrz/npaper";
  };

  outputs = { nixpkgs, npaper, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [ npaper.packages.${pkgs.stdenv.hostPlatform.system}.default ];
        })
      ];
    };
  };
}

nix run github:lonerOrz/npaper

qs -c npaper

All settings are managed through the in-app Settings panel (S key):

• Wallpaper Directories — Add/remove multiple wallpaper folders
• Cache Directory — Thumbnail cache location (default: ~/.cache/wallpaper_thumbs)

• API Key — Your Wallhaven API key (optional, increases rate limit)
• Download Folder — Custom download location for remote wallpapers (optional, falls back to first wallpaper directory)
• Filters — Toggle categories (General, Anime, People) and purity (Safe, Sketchy, NSFW)

• Overlay Opacity — Background dimming level
• Border Glow — Enable/disable active card glow effect
• Card Shadow — Enable/disable card drop shadows
• Background Preview — Show wallpaper preview behind cards

This project is licensed under the BSD 3-Clause License.

If you find npaper useful, please give it a ⭐ and share! 🎉