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

Fix a black lock screen when the wallpaper is a WebP image

omarchyomarchy-4archhyprlandwayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

The package name is correct and the remedy works, but the stated cause is now obsolete: qt6-imageformats IS listed in install/omarchy-base.packages, and migrations/1787133200.sh adds it to existing installs, so it is no longer true that it 'is not a dependency of the omarchy package'. On a current system the fix is to run omarchy update and let the migration do it. Also sudo pacman -S qt6-imageformats against a stale sync db can fail or pull an outdated version. -Syu is the correct form (and -Sy alone would be a partial upgrade).

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

Symptom

The desktop wallpaper displays perfectly, but omarchy system lock shows a solid black background instead of the wallpaper. Wallpaper thumbnails in the picker panels are blank too. Confusing because "the wallpaper works, so why is the lock screen black?"

Cause

omarchy-shell runs on Qt6/Quickshell, and QML Image needs a codec plugin in /usr/lib/qt6/plugins/imageformats/. Without libqwebp.so there, WebP decodes to nothing. The desktop looks fine because Hyprland's wallpaper daemon decodes WebP independently of Qt. This is now a stale-install problem rather than a packaging gap: qt6-imageformats **is** listed in install/omarchy-base.packages, and migrations/1787133200.sh adds it to existing installs, so it bites machines that predate that migration and have not run omarchy update.

Fix

The cause is out of date: qt6-imageformats is now listed in install/omarchy-base.packages, and migration 1787133200 adds it to existing installs. So run the update first. On a current system it fixes this for you:


omarchy update

Confirm the codec is present:


ls /usr/lib/qt6/plugins/imageformats/ | grep -i webp   # want libqwebp.so

If it is still missing, install it. Use -Syu, never bare -S against a stale sync db and never -Sy (partial upgrade):


sudo pacman -Syu qt6-imageformats
omarchy restart shell

The underlying explanation still holds: the Quickshell-based omarchy-shell needs a Qt image-format plugin to decode WebP, while the desktop wallpaper looks fine because Hyprland's wallpaper daemon decodes WebP independently of Qt.

Alternatively convert the wallpaper:


magick ~/Pictures/wall.webp ~/Pictures/wall.jpg
omarchy theme bg set ~/Pictures/wall.jpg

Verify

ls /usr/lib/qt6/plugins/imageformats/ | grep webp shows libqwebp.so, and omarchy system lock displays the WebP wallpaper. Previews in the wallpaper picker render instead of being blank.

Sources

webp-wallpaper-black-lock-screen