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
| Setter | Session | Used by |
|---|---|---|
| swaybg | Wayland | Sway |
| swww | Wayland | Hyprland (with fade transitions) |
| hyprpaper | Wayland | Hyprland |
| feh | X11 | i3, bspwm, dwm |
| nitrogen | X11 | openbox, bspwm |
| xwallpaper | X11/Wayland | general purpose |
fuzz-wall picks whichever one is installed. If you have multiple, it prefers in the order listed above.
| WM / Compositor | Session |
|---|---|
| Sway | Wayland |
| Hyprland | Wayland |
| river | Wayland |
| dwl | Wayland |
| i3 | X11 |
| bspwm | X11 |
| dwm | X11 |
| openbox | X11 |
| xfwm | X11 |
Required:
At least one wallpaper setter:
Optional:
libnotify— for error notifications vianotify-send
paru -S fuzz-wall
# or
yay -S fuzz-wallgit 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-wallControls inside fuzzel:
- Type to filter wallpapers
Enterto applyESCto exit
No config file needed. The only option is:
| Env var | Default | Description |
|---|---|---|
FUZZ_WALL_DIR |
~/Pictures/wallpapers |
Directory to pick wallpapers from |
You can set it permanently in your shell rc:
export FUZZ_WALL_DIR=~/Pictures/wallsOr 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 fuzzelNo 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/wallpapersfuzz-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