Walt is a wallpaper manager for Hyprland with both a terminal UI and a native desktop GUI. It lets you browse, preview, apply, randomize, and rotate wallpapers using hyprpaper, while keeping the TUI fast for keyboard-heavy workflows and the GUI focused on preview-driven browsing.

• Browse and apply wallpapers from the terminal or native GUI
• Preview wallpapers before switching
• Manage multi-display wallpaper assignment
• Apply random wallpapers from the app or CLI
• Control a background rotation service
• Manage wallpaper directories and themes

Install Walt quickly:

yay -S walt-bin

If you're on Arch Linux, refer to the Install section for walt-git and walt-bin.

Start using the app with:

walt

• walt
  • keyboard-first terminal workflow
  • in-terminal preview
  • best for fast browsing

• walt gui
  • native desktop window
  • larger visual preview
  • better for pointer-driven browsing and dialogs

• hyprpaper
• hyprctl
• an image-capable terminal for the TUI preview only:
  • Ghostty
  • Kitty
  • WezTerm

Build from source only:

• rust and cargo

Quick install:

curl -fsSL https://raw.githubusercontent.com/gitfudge0/walt/main/install.sh | bash

If you're on Arch, use your preferred AUR helper:

yay -S walt-git

For the prebuilt release package:

yay -S walt-bin

walt-git builds from the latest source tree. walt-bin installs the tagged binary release.

This installs walt to ~/.local/bin/walt.

From a local checkout:

./install.sh

Manual install:

cargo build --release
install -Dm755 target/release/walt ~/.local/bin/

If you're on Nix, you can use flake.nix:

To run it:

nix run github:gitfudge0/walt

To install it to your profile:

nix profile add github:gitfudge0/walt

Or in order to install declaratively, add this to your flake.nix:

{
    inputs = {
        nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
        walt.url = "github:gitfudge0/walt";
    };

    outputs = {walt, nixpkgs, ...}:
    {
        nixosConfigurations."<your-hostname>" = nixpkgs.lib.nixosSystem {
            system = "x86_64-linux"; # or "aarch64-linux"
            modules = [
                ({ pkgs, ... }: {
                    environment.systemPackages = [
                        walt.packages.${pkgs.system}.default
                    ];
                })
            ];
        };
    }
}

1. Launch walt for the terminal UI or walt gui for the desktop GUI.
2. Paste the path to your wallpaper directory.
3. Press Enter.

The GUI folder picker may depend on an XDG desktop portal or native dialog backend on Linux.

Walt stores its config in ~/.config/walt/. If you have older settings in ~/.config/wallpaper-switcher/, Walt will read them automatically.

For Ghostty:

bind = $mainMod SHIFT, D, exec, ghostty --class=walt -e ~/.local/bin/walt
bind = $mainMod CTRL, D, exec, ~/.local/bin/walt gui
bind = $mainMod, D, exec, ~/.local/bin/walt random
windowrulev2 = float, class:^(com\.mitchellh\.ghostty\.walt)$
windowrulev2 = size 900 600, class:^(com\.mitchellh\.ghostty\.walt)$
windowrulev2 = center, class:^(com\.mitchellh\.ghostty\.walt)$

$mainMod + Shift + D opens the Walt TUI. $mainMod + Ctrl + D opens the GUI. $mainMod + D applies a random wallpaper immediately.

install.sh detects Ghostty, WezTerm, or Kitty and prints matching launch instructions.

If you want the GUI to float, the windowrulev2 examples above apply to the GUI window class as well.

Make sure hyprpaper is running:

exec-once = hyprpaper

Walt works across older and newer hyprpaper behavior and falls back gracefully when active wallpaper status is unavailable.

Debug logs are written to ~/.cache/walt/logs/walt.log. Use WALT_LOG=debug to increase verbosity.

Walt ships with a native egui desktop interface alongside the original TUI. The GUI keeps the same core capabilities as the terminal app:

• wallpaper browsing and large preview
• multi-display apply flows
• random wallpaper actions
• rotation service controls
• wallpaper path management
• uninstall flow

If you do not have a graphical session available, walt gui exits with a clear error and you can still use walt for the terminal interface.

The GUI folder picker uses your Linux desktop portal or native dialog backend. On Hyprland, install a matching XDG desktop portal backend such as xdg-desktop-portal-gtk or xdg-desktop-portal-kde if folder selection does not appear.

walt
walt --version
walt -v
walt gui

• walt launches the terminal wallpaper browser
• walt --version and walt -v print the installed Walt version
• walt gui launches the native desktop GUI

walt random
walt random --same
walt random 0

walt random applies different random wallpapers across all detected displays when possible.

walt random --same applies one random wallpaper to every display.

walt random 0 applies one random wallpaper to display 0. Display indices are zero-based and clamp to the last detected display if the requested index is out of range.

walt rotation install
walt rotation status
walt rotation interval 900
walt rotation disable
walt rotation enable
walt rotation uninstall

• install installs and starts the user service
• status shows the current service state
• interval 900 sets the rotation interval in seconds
• disable stops the installed service
• enable starts it again
• uninstall removes it completely
• while the service is running, newly attached displays are handled automatically

Walt does not auto-rotate wallpapers while the TUI is open unless you install the background service. When rotate-all mode is enabled from the TUI, Entries changes to all wallpapers. The rotation status also shows whether displays rotate with the same wallpaper or different wallpapers per display. When the rotation service is running, hotplug behavior follows the display mode:

• same on all displays mirrors the current wallpaper onto the new display
• different per display assigns a fresh random wallpaper to only the new display

walt uninstall

Prompts before removing the rotation service, config, cache, and installed ~/.local/bin/walt binary.

For non-interactive use:

walt uninstall --yes

Walt opens with the current wallpaper selected in the All list when it is already indexed.

• ↑/↓ or j/k move
• Tab or l switch between All and Rotation
• Shift+Tab or h switch to the previous section
• g/G jump to the top or bottom
• Enter apply the selected wallpaper directly when one display is detected, or open a display picker when multiple displays are detected
• A apply the selected wallpaper to all displays
• / filter the active section
• s toggle sort for the active section between name and modification date
• r add or remove the selected wallpaper from the manual rotation list
• Ctrl+r apply a random wallpaper directly when one display is detected, or open random options when multiple displays are detected
• R open the rotation options for service actions, wallpaper scope, and display mode
• All displays in the display picker applies the selected wallpaper to every display from inside the popup
• i change the interval used by the installed rotation service
• p manage wallpaper paths
• t open the theme picker
• ? open the keybindings popup
• q or Esc quit

walt rotation enable and walt rotation disable still control only the background service. The rotate-all toggle and the same/different display rotation mode are available only from the R popup.

The TUI uses focused popups for display selection, random options, rotation controls, path management, and theme selection.

• Appears after Enter when multiple displays are detected
• Lists each detected display plus All displays
• ↑/↓ or j/k move
• Enter apply
• Esc or q close

• Appears after Ctrl+r when multiple displays are detected
• Offers:
  • Different on all displays
  • Same on all displays
  • one random target per display, shown as Display N: <name>
• Display indices in the popup match the CLI walt random N numbering
• ↑/↓ or j/k move
• Enter apply
• Esc or q close

• Open with R
• Lets you install or enable the service, switch between selected wallpapers and all wallpapers, choose same-on-all-displays or different-per-display rotation, and change the interval
• ↑/↓ or j/k move
• Enter run the selected action
• Esc close

• ↑/↓ or j/k move
• a add a path
• d remove the selected path
• p, q, or Esc return
• t open the theme picker

• Type a path manually
• Tab completes from the suggestions list
• Enter add the selected path
• Esc cancels only when this flow was opened from the path manager

• ↑/↓ or j/k preview themes
• Enter confirm
• Esc or q cancel

Walt includes these themes:

• System
• Catppuccin Mocha
• Tokyo Night
• Gruvbox Dark
• Dracula
• Nord
• Solarized Dark
• Kanagawa
• One Dark
• Everforest Dark
• Rosé Pine

System uses your terminal defaults. The named themes use opaque surfaces for a cleaner in-app look.

cargo build --release

The binary will be available at target/release/walt.

MIT