Omarchy Wallpapers

Personalized wallpapers inspired by the official Omarchy Linux ones. They keep the visual style of the themes installed on Omarchy while offering more specific content variations.

Support the project

This project is developed in the spare time and passion that all open-source developers share freely. But the hours of work are only half the story: every wallpaper here is generated with AI, and producing them consumes millions of AI tokens. Passion covers the time, but it cannot cover the tokens.

Sponsor on GitHub

Installing Plugin

The easiest way to manage the wallpapers in this repository is to install the Omarchy Linux plugin directly: https://github.com/emkcloud/omarchy-wallpapers-plugin. It provides an interface to browse, install, and set wallpapers for your theme. For many, the quickest way is the install command:

omarchy plugin add https://github.com/emkcloud/omarchy-wallpapers-plugin.git --enable --yes

If you prefer to install them manually, follow the steps below.

Installing wallpapers

Installing with an AI agent

The easiest way, no commands needed: copy this prompt to your default AI agent.

- Copy the wallpapers from the emkcloud/omarchy-wallpapers repository.
- Take only the ones in images/tokyo-night/countries.
- Install them into Omarchy's Tokyo Night backgrounds directory.
- Refresh the background cache with `omarchy theme bg cache`.

To install a different theme, replace tokyo-night with its folder name under images/ (e.g. osaka-jade).

Installing from the command line

Since there can be many wallpapers, it is convenient to download only the ones from the themes you need. First download the install script:

curl -fsSL -o wallpapers.py \
    https://raw.githubusercontent.com/emkcloud/omarchy-wallpapers/main/scripts/wallpapers.py

Then run it: it downloads only the wallpapers of the requested theme, e.g. the osaka-jade ones (parallel downloads from catalog.json, files already up to date are skipped):

python3 wallpapers.py install osaka-jade

The script refreshes the background cache automatically; no extra step needed. The wallpapers show up once you switch to that theme — you can install several themes without changing the active one each time.

To install a different theme, replace osaka-jade with its folder name under images/ (e.g. tokyo-night).

Installing a collection

Wallpapers are grouped into collections (content types, e.g. countries, cities, figures). To install only the wallpapers of one collection, pass its name as an extra argument (both the plural and singular forms work):

python3 wallpapers.py install tokyo-night countries

Installing a single wallpaper

To install only one wallpaper of a theme, add its name (country name or code) as an extra argument:

python3 wallpapers.py install tokyo-night Italy

To pick the wallpaper from a specific collection, pass the collection name before it:

python3 wallpapers.py install tokyo-night countries Italy

Version

The script embeds its version. Print it with:

python3 wallpapers.py --version

Masters (for contributors)

The masters/ folder holds the base images in full color, one folder per content type under masters/colors/ (e.g. masters/colors/countries/). Every themed wallpaper is derived from a master by applying the theme's color scheme on top of it, so a single master can produce several wallpapers that adapt to different colors.

Datasets (for developers)

The datasets/ folder is generated by scripts/generate_dataset.py — never edit it by hand. It is organized per collection, so a program can discover the whole file hierarchy by downloading a single file.

datasets/
  config.json         # static source
  datasets.json       # top-level index
  masters/
    catalog.json      # masters catalog
    collections.json  # collection stats
    optimization.json # optimization cache
  osaka-jade/
    catalog.json      # theme catalog
    collections.json  # collection stats
    optimization.json # optimization cache
    previews.json     # previews cache
  tokyo-night/
    catalog.json      # theme catalog
    collections.json  # collection stats
    optimization.json # optimization cache
    previews.json     # previews cache

Showcase

Available themes

• Gruvbox — retro groove color scheme with warm earthy browns and muted greens.
• Matte Black — matte black backgrounds with a strong orange accent.
• Nord — cold, muted blue-gray tones from the Nord palette, with crisp arctic-inspired contrast.
• Osaka Jade — a fresh jade green palette with warm highlights.
• Tokyo Night — deep blue backgrounds with cyan and purple neon accents.

Listing wallpapers

The wallpapers.py script can list the available themes, or the wallpapers of a specific theme. Download it first:

curl -fsSL -o wallpapers.py \
    https://raw.githubusercontent.com/emkcloud/omarchy-wallpapers/main/scripts/wallpapers.py

List the available themes:

python3 wallpapers.py list

List all the wallpapers of a theme:

python3 wallpapers.py list tokyo-night

List only the wallpapers of a collection (e.g. countries):

python3 wallpapers.py list tokyo-night countries

Remove wallpapers

To remove a theme's wallpapers from Omarchy, use the remove command. Only the wallpapers from this repository are deleted: any file you added yourself in the theme's backgrounds folder is kept.

python3 wallpapers.py remove osaka-jade

To remove only the wallpapers of a collection, pass its name as an extra argument:

python3 wallpapers.py remove osaka-jade countries

To remove a single wallpaper, add its name (country name or code) as an extra argument:

python3 wallpapers.py remove tokyo-night Italy

To remove a wallpaper from a specific collection, pass the collection name before it:

python3 wallpapers.py remove tokyo-night countries Italy

To remove every theme's installed wallpapers in one go, use --all:

python3 wallpapers.py remove --all

The background cache is refreshed automatically.

Wallpapers image optimization

All images are WebP (2560x1440 for the -2K versions), the same format Omarchy 4 renders as backgrounds. Masters are encoded lossless (pixel-exact source of truth); the small loss (lossy q85) is applied only when deriving the themed wallpapers from a master, so the masters stay intact.

Lossless re-compression is handled by scripts/generate_optimization.py (or the omarchy-wallpapers-generate-optimization skill), which caches results per collection in datasets/<collection>/optimization.json.

Contributing

Want to add a custom wallpaper? Follow the conventions described in AGENTS.md.

License

This project is licensed under the MIT License.