Backgrounds

How backgrounds work

Put image files directly in your theme’s backgrounds/ directory. Omarchy looks one level deep — nested directories are ignored — and recognises .jpg, .jpeg, .png, .gif, .bmp and .webp, case-insensitively.

It collects your theme’s backgrounds together with anything the user has dropped in ~/.config/omarchy/backgrounds/<theme>/, sorts the combined list by path, and advances to the next one. Super + Ctrl + Space cycles through them. The active image is the ~/.local/state/omarchy/current/background symlink.

Because the list is sorted, filenames are ordering. Numbered prefixes — 001-harbor-dusk.jpg, 002-late-shift.jpg — put your best image first and keep the sequence stable as you add more.

A theme with no backgrounds still works: Omarchy notifies that none was found and applies the palette anyway. A theme with one good background is better than one with twelve mediocre ones.

Sizes and formats

• Ship at least 2560×1440, and prefer 3840×2160. Anything smaller is visibly soft on a modern laptop panel.
• Use JPEG for photographs and PNG for flat, graphic or gradient artwork. WebP is supported and is a good compromise for large photographic images.
• Keep each file under about 3 MB. People clone your theme over the network, and an eight-image repository at 10 MB an image is a 80 MB clone for a colour scheme.
• Match the theme. The background is what people see first; a wallpaper whose colours fight the palette undoes the palette.
• Avoid heavy detail and high contrast in the top strip and the bottom corners, where the bar and notifications sit.
• Bear in mind that SVG is not an accepted background format, and that this gallery declines SVG uploads for the same reason: it is a document format that can carry script.

Licensing and attribution

This is the part most theme repositories get wrong. Publishing a theme means redistributing every image in it. A licence on your colors.toml says nothing about the wallpaper sitting next to it.

• Only ship images you made, images you hold a redistribution licence for, or images under a licence that permits redistribution. "I found it on a wallpaper site" is not a licence.
• Record the source of every image — in README.md, or in a backgrounds/CREDITS.md. Photographer or creator, source URL, and licence.
• Where a licence requires attribution, such as CC BY, reproduce it in full. Attribution is a condition, not a courtesy.
• Say so if an image is AI-generated, and name the tool. Some people will not want it, and they are entitled to know.
• Give your palette its own licence. MIT is a good default and is what the Theme Studio offers; note explicitly that it covers colors.toml and not the backgrounds, if their terms differ.

This gallery caches repository images privately until a maintainer has confirmed redistribution rights. Clear attribution in your README is what makes that review straightforward — and fast.