Omarchy wallpapers: personal backgrounds, cropping, video and recovery

A wallpaper is media behind your windows; a theme supplies application colors and other styling. You can keep Catppuccin, Gruvbox or another palette and replace only the picture. This is often the better first experiment when the text is readable but the desktop image is distracting.

Understand where backgrounds come from

The official backgrounds guide provides the menu workflow. In the pinned layout, selection combines the active theme’s backgrounds/ with your personal folder for that theme, then updates a current-background link and the running shell.

theme backgrounds + ~/.config/omarchy/backgrounds/<theme>/
  → ordered candidates
  → current/background symlink
  → shell background update
  → rendering on the display surfaces

Location	Use it for
~/.config/omarchy/backgrounds/<theme>/	Your images retained separately from bundled source
Theme source’s backgrounds/	Assets supplied by that theme
~/.local/state/omarchy/current/background	Inspecting the current selection; not a storage folder
~/.local/state/omarchy/current/theme/	Generated theme state; not permanent personal assets

The pinned selection helper looks for files at the folders’ top level, not recursively through arbitrary nested albums. Moving a referenced image later can break the current link.

Add a static image and verify the result

1. Check the current theme through the picker or omarchy-theme-current in the pinned command set.
2. Choose Install → Style → Background. The official workflow opens the personal directory for that theme.
3. Copy an image there, keeping an original elsewhere. Use a filename you can recognize and an asset you may use.
4. Cycle with Super + Ctrl + Space until it appears. The palette should remain selected.
5. Switch to another theme and back. Remember that its personal background folder is a different directory.

The pinned selector recognizes JPG/JPEG, PNG, GIF, BMP, WebP and listed video extensions. Extension recognition does not guarantee a damaged file can decode. Do not rename a different format to .png as a repair.

For a deliberate direct selection in this command set:

omarchy-theme-bg-set "$HOME/Pictures/my wallpaper.png"

Replace that path with an existing image. Quotes preserve spaces. The setter resolves the file and points current state at it; it does not copy it into your personal collection. Use the personal folder if you want it included in normal cycling.

Why a picture is cropped

The pinned still-image renderer uses aspect-preserving crop: fill the surface while retaining the image’s proportions. It scales until neither dimension leaves an empty edge, then clips the excess.

For image dimensions Iw × Ih and a surface Sw × Sh:

scale = max(Sw / Iw, Sh / Ih)
displayed dimensions = Iw × scale, Ih × scale
excess width/height = displayed dimensions − surface dimensions

For a 3840 × 2160 picture on a 1920 × 1080 surface, the aspect ratios match, so no aspect-ratio cropping is needed. On a 1080 × 1920 portrait surface, scaling to height produces a picture about 3413 pixels wide; only about 31.6% of its original width can be visible. More source resolution does not fix that composition problem.

For portrait or mixed-ratio displays, choose images with important content near the center and space around it, or create a crop suited to the target ratio. Compare both displays after selection. This guide does not invent a supported per-monitor wallpaper command; check your installed shell’s current features before promising independent images. A single current-background link does not mean the picture is shown as one stretched canvas spanning every monitor.

Video is a separate resource choice

The official guide lists MP4, M4V, MOV, WebM, MKV and AVI, using OWE for video backgrounds. It describes shared decoding across monitors, pausing when hidden, and muted/cached-still handling on the lock surface. GIF handling also differs between desktop and lock. These behaviors depend on the installed integration, and the boot-unlock image is another surface again.

Start with a short local clip and check codec compatibility, CPU/GPU activity, sound, lock behavior and your laptop’s normal battery use. Shared decoding does not mean zero rendering cost. This guide has no measured battery percentage to promise. Return to a static image if animation or audio interferes with work; disabling the entire shell is unnecessary.

Diagnose the first broken link

Use read-only inspections for the pinned state path:

omarchy-theme-current
readlink -f ~/.local/state/omarchy/current/background
file -- "$HOME/Pictures/my wallpaper.png"

The last path is your real candidate, not necessarily the current one. file identifies content; a resolved link should point to a file that still exists.

Symptom	Check first
Added image never appears in cycling	Correct theme folder, top-level placement and supported extension
Direct selection works but cycling skips it	Direct selection did not add it to a searched folder
Background disappears after moving files	The current link’s target and file access
New file at same path still shows old pixels	Select another image and return; investigate caching before editing theme colors
Wide scene loses its subject on portrait monitor	Aspect ratio and composition, not an ISO/install issue
Desktop moves, lock or boot image does not	Different rendering surfaces and their documented behavior
Palette changes unexpectedly too	You selected a theme rather than only a background

To recover, select a known-working theme background or reapply the original theme. Back up personal assets before removing them; do not delete the whole current-state directory as a wallpaper reset. For permanent palette changes see application theming; for screen layout and scale see displays.