i3 Desktop Part 11: A Visual Wallpaper Picker

Changing wallpaper in i3

Changing a wallpaper in i3 is easy. One feh command is enough. The difficult part is choosing an image from many files. It is also hard to remember the active image. The image must return after an i3 reload or monitor change.

The original .local/bin/i3-wallpaper script handled only the last part. It read a path from a config file. It applied that image. It used a solid colour if something was missing. This was reliable. Changing the wallpaper still required browsing files separately. Or I had to edit the saved path by hand.

The new version keeps this simple foundation. It adds a visual rofi gallery.

Mod+Shift+g opens the picker directly:

~/.local/bin/i3-wallpaper menu

It is also available as Wallpaper in the control centre under Mod+u. The direct shortcut is useful when I know what I want. The control centre keeps the feature discoverable when I forget the binding.

The script searches ~/.config/wallpapers recursively by default. It recognises JPEG, PNG, WebP, BMP, GIF, and TIFF files. It includes readable symbolic links. Results are sorted consistently. They show paths relative to the wallpaper directory. Nested folders remain useful. Long home-directory paths do not fill the menu.

Rofi displays results as a two-row, three-column gallery. Each entry has a large image preview. The filename is below it. Fuzzy search is enabled. Typing part of a name reduces a large collection to a few choices.

The saved wallpaper opens preselected and highlighted. Enter applies the selected image. Escape closes the gallery without changing anything.

Passing image previews to rofi

Normal dmenu input is a list of text. Rofi also accepts metadata after each entry. This lets the script attach an icon path to the label:

printf '%s\0icon\x1f%s\n' "$label" "$wallpaper"

The dedicated .config/rofi/i3-wallpaper.rasi theme renders that icon at 220 pixels. It places the filename underneath. It uses the same Catppuccin Frappe colours. It uses mauve selection, rounded panels, and JetBrains Mono font. This matches the rest of the desktop.

The menu asks rofi to return the selected row number. It does not return the displayed text. That number maps directly back to the wallpaper array. Paths can contain spaces. Two images in different folders can share a filename. Neither case makes the selection ambiguous.

The file scan is null-delimited for the same reason. A wallpaper filename should not break discovery because it contains spaces.

Applying and remembering the choice

The actual wallpaper command stays deliberately plain:

feh --no-fehbg --bg-fill "$wallpaper"

--bg-fill fills the display without stretching the image. --no-fehbg stops feh from creating its own wallpaper state file. This script owns that state.

Only after feh succeeds does the script save the selected path to:

~/.config/i3/wallpaper

Paths inside the home directory are stored with a literal ~/ prefix. They do not use the full home path. The script expands that prefix when reading it again. This keeps the selection portable. It works if the dotfiles are restored under a different username or home-directory location.

A dunst notification confirms the chosen filename. Missing files produce useful notifications. An empty gallery produces useful notifications. An unavailable rofi or feh command produces useful notifications. Failed saves produce useful notifications. They do not disappear silently.

If the saved image cannot be read during a normal startup apply, the script uses xsetroot. It uses the Catppuccin base colour. A broken path leaves a clean desktop. It does not leave a half-restored background.

Surviving reloads and monitor changes

The picker is less useful if the choice lasts only for the current session.

The i3 config runs the script with no arguments through exec_always:

exec_always --no-startup-id ~/.local/bin/i3-wallpaper

With no subcommand, the script reads the saved selection. It applies it. The wallpaper comes back at login. It also returns whenever i3 is reloaded.

The monitor layout and scaling scripts call it too. Changing outputs with xrandr changes the shape of the desktop. The image needs to be applied again. It must fill the new arrangement correctly. Both helpers re-run i3-wallpaper after a successful display change.

This creates a small restoration loop:

  1. The gallery applies and saves a wallpaper.
  2. i3 startup or reload reads the saved path.
  3. Monitor layout and scaling changes reapply it for the new geometry.

There is no wallpaper daemon. There is no second source of truth.

Moving the image directory

Keeping wallpapers inside the dotfiles works for the small set currently in the repository. The gallery does not require that layout.

The script loads .config/i3/theme.env. Another directory can be configured there:

I3_WALLPAPER_DIR="$HOME/Pictures/Wallpapers"

The picker, default path, labels, and file scan all follow that setting. This lets the code stay in the dotfiles. A larger or private image collection can live somewhere more appropriate.

Useful without the menu

The script is still a command-line tool underneath the gallery:

i3-wallpaper                 apply the saved wallpaper
i3-wallpaper menu            open the visual picker
i3-wallpaper list            print every discovered image
i3-wallpaper set PATH        apply and persist a specific image
i3-wallpaper PATH            apply an image without changing the saved choice

These commands make the individual parts easy to test. list checks discovery. A bare path checks feh and the fallback behaviour. set checks application and persistence together. The rofi gallery is an interface to those behaviours. It is not the only way to reach them.

A small piece of desktop behaviour

A wallpaper picker is not essential infrastructure. It is a small feature that makes this i3 setup feel like a complete desktop.

The normal path is visual and quick. The current choice is obvious. The result survives reloads and display changes. Underneath, everything is still a shell script. It uses a text file, rofi, feh, and xsetroot.

This is the balance I want from this environment. Common actions should feel comfortable. The implementation stays simple enough to inspect when something does not work.