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.

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. Download the install script and 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):

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

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 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

Masters (for contributors)

The masters/ folder holds the base images in full color, one folder per content type (e.g. masters/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 color schemes.

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/
  datasets.json       # top-level index
  masters/
    catalog.json      # masters catalog
    optimization.json # optimization cache
  osaka-jade/
    catalog.json      # theme catalog
    optimization.json # optimization cache
    previews.json     # previews cache
  tokyo-night/
    catalog.json      # theme catalog
    optimization.json # optimization cache
    previews.json     # previews cache

Showcase

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
osaka-jade
tokyo-night

List all the wallpapers of a theme:

$ python3 wallpapers.py list tokyo-night
omarchy-country-AD-Andorra-2K.webp
omarchy-country-AE-United-Arab-Emirates-2K.webp
omarchy-country-AF-Afghanistan-2K.webp
...

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 a single wallpaper, add its name (country name or code) as an extra argument:

python3 wallpapers.py remove tokyo-night Italy

The background cache is refreshed automatically.

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/optimize_images.py (or the /omarchy-optimize-images command), 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.