A minimal, distro-agnostic wallpaper picker powered by fuzzel.

fuzz-wall lets you browse and set wallpapers interactively using fuzzel's dmenu mode. It auto-detects your wallpaper setter, works on both Wayland and X11, and has zero config files.

• Works on Wayland and X11
• Auto-detects your installed wallpaper setter
• Override wallpaper directory with an env var — no config editing
• No dependencies beyond fuzzel and a wallpaper setter
• Tiny — just a single POSIX sh script

fuzz-wall picks whichever one is installed. If you have multiple, it prefers in the order listed above.

Required:

• fuzzel

At least one wallpaper setter:

• swaybg
• swww
• feh
• nitrogen
• xwallpaper

Optional:

• libnotify — for error notifications via notify-send

paru -S fuzz-wall
# or
yay -S fuzz-wall

git clone https://github.com/youngcoder45/fuzz-wall
cd fuzz-wall
chmod +x fuzz-wall
cp fuzz-wall ~/.local/bin/

Make sure ~/.local/bin is in your $PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

# Pick a wallpaper interactively
fuzz-wall

# Use a custom wallpaper directory
FUZZ_WALL_DIR=~/Pictures/walls fuzz-wall

Controls inside fuzzel:

• Type to filter wallpapers
• Enter to apply
• ESC to exit

No config file needed. The only option is:

You can set it permanently in your shell rc:

export FUZZ_WALL_DIR=~/Pictures/walls

Or in your WM config (e.g. Hyprland):

bind = $mod, W, exec, FUZZ_WALL_DIR=~/Pictures/walls fuzz-wall

Sway (~/.config/sway/config):

bindsym $mod+w exec fuzz-wall

Hyprland (~/.config/hypr/hyprland.conf):

bind = $mod, W, exec, fuzz-wall

i3 (~/.config/i3/config):

bindsym $mod+w exec fuzz-wall

fuzzel not found: Install fuzzel from your distro's package manager.

# Arch
sudo pacman -S fuzzel

No wallpaper setter found: Install one of the supported setters listed above.

Wallpaper directory not found: Make sure ~/Pictures/wallpapers exists, or set FUZZ_WALL_DIR to your wallpaper folder.

mkdir -p ~/Pictures/wallpapers

fuzz-wall command not found: Make sure ~/.local/bin is in your $PATH (see install section above).

Contributions are welcome! See CONTRIBUTING.md for guidelines.

MIT © Aditya