OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-theming low occasional DISPUTE

Fix a theme switch that keeps showing the previous theme's wallpaper

omarchywallpaperquickshelltheming
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

#14191 (open) reports the stale wallpaper on a quattro checkout at 8e02fc84 and attributes it to BackgroundMedia caching by URL (cached: version === 0). Confirmed locally: 18 of 22 stock themes in /usr/share/omarchy/themes ship backgrounds/omarchy.png, and omarchy-theme-set passes the durable path under ~/.local/state/omarchy/current/theme/backgrounds as the final background. But the record's cause describes 4.0.4-1 code it did not read closely: 4.0.4-1's Background.qml has no BackgroundMedia, and its base Image (cache: true) is bound to displayedBackground, which is the same string before and after such a switch, so the base frame is not reloaded at all and caching is not the operative step. Whether the visible desktop is stale on 4.0.4 then depends on the incomingFrame layer, which stays set because finishingTransition never clears. I could not exercise this, because running omarchy-theme-set on the operator's workstation is forbidden. The fix led with omarchy theme bg next ... then back, but switching back to the same path can hit the URL-keyed cache again, so the reliable step (restart the shell) now comes first. Cause rewritten to separate what the issue showed from what 4.0.4 code implies.

The cause above was rewritten on 2026-10-05 to match this note; the fix was corrected by the audit itself.

Symptom

I switch themes, the colors change, but the wallpaper still shows the old theme's image. It happens when both themes have a wallpaper with the same file name, most often omarchy.png, which 18 stock themes each ship with different pixels. Switching to a wallpaper with a different name works.

Cause

Both themes' backgrounds land at the same durable path, for example ~/.local/state/omarchy/current/theme/backgrounds/omarchy.png, because omarchy-theme-set copies the new theme into ~/.local/state/omarchy/current/theme and hands that path to the shell as the final background. 18 of the 22 stock themes in 4.0.4-1 ship a backgrounds/omarchy.png. The reporter of #14191 reproduced the stale image on a quattro checkout at 8e02fc84, where BackgroundMedia caches images by URL, so the old theme's decoded image is reused for the unchanged path. The 4.0.4-1 code differs: shell/plugins/background/Background.qml has no BackgroundMedia, and its base Image is bound to the path string, which does not change across such a switch, so the base frame is never reloaded. Whether the desktop visibly stays stale on 4.0.4-1 depends on the transition layer drawn over it, and that was not reproduced on 4.0.4. The issue is still open.

Fix

Restart the shell. It starts with an empty image cache and loads whatever current/background points at now:


omarchy-restart-shell

Run it from a terminal inside the desktop session. Do not run omarchy-restart-shell from an ssh session or while the screen is locked: on a session whose locker has died it re-locks, and the lock cannot be released headlessly.

A lighter workaround is to move to a wallpaper with a different file name:


omarchy theme bg next

Switching back to the same-named file later can show the old theme's image again, because the cache is keyed by path. Use the restart if that happens.

To avoid it for your own wallpapers, give them names that are unique across themes, for example prefix the theme name: ~/.config/omarchy/backgrounds/<theme>/<theme>-omarchy.png.

Verify


readlink -f ~/.local/state/omarchy/current/background

The path belongs to the new theme and the desktop matches it.

Sources

theme-switch-same-filename-wallpaper-stale