Make a theme worth keeping.

A theme is a directory of colour

An Omarchy theme is a plain directory. It holds one colors.toml palette, usually a backgrounds/ folder, and optionally a few per-application colour files. There is no build step, no manifest, and no packaging format. If you can edit a text file and push a Git repository, you can publish a theme.

Omarchy reads your palette once and generates the configuration every themed application needs: the terminal, btop, Chromium, Hyprland, Neovim, Helix, VS Code, Obsidian, and every surface of the Omarchy shell — the bar, the menu, notifications, the on-screen display, and the lock screen. You write roughly thirty colours; Omarchy writes the rest.

Everything on these pages was checked against a real Omarchy install running version 4.0.0.alpha. Where behaviour changed between releases, both forms are described.

Where themes live

Anything inside the first directory shows up in the theme picker. That is the entire registration mechanism.

What happens when a theme is applied

omarchy theme set <name> does the same six things every time. Knowing them explains most surprises.

1. Take a lock, so two theme switches queue instead of racing, and empty the staging directory at ~/.local/state/omarchy/current/next-theme.
2. Copy the bundled theme of that name, if one exists.
3. Overlay your copy from ~/.config/omarchy/themes/<name>/ on top — in full if you wrote it, filtered if it came from a Git clone.
4. If the staged theme has no colors.toml but does have an alacritty.toml, derive a palette from the terminal colours.
5. Render every template in ~/.config/omarchy/themed/ and then $OMARCHY_PATH/default/themed/, skipping any file the theme already supplied.
6. Swap the staged directory into place as current/theme, write current/theme.name, hand the palette to the running shell, then retint the applications that are already open and fire the theme-set hook.

The fifth step is the one worth remembering: a file you ship always beats the file Omarchy would have generated. Shipping your own btop.theme means Omarchy never renders the template for it.

Two ways to start

Copy an existing theme and edit it, or start from a blank palette in a colour editor. Both end in the same place — a directory with a colors.toml in it.

• By hand: copy a bundled theme into ~/.config/omarchy/themes/, edit colors.toml, and switch to it. Step by step.
• In this gallery: build a palette in the Theme Studio, watch it against a simulated desktop, check contrast as you go, and publish it as an installable repository.
• On your desktop: Omarchy ships Aether, a graphical theme builder, under Super + Alt + Space.

The whole file tree

Only colors.toml is genuinely required. Everything else is optional, and a good first theme ships three files.

omarchy-yourname-theme/
├── colors.toml              the palette — the only required file
├── backgrounds/             wallpapers, cycled with Super + Ctrl + Space
│   ├── 001-first-light.png
│   └── 002-late-shift.png
├── icons.theme              one line: the GTK icon set name
├── preview.png              thumbnail for the theme picker
├── unlock.png               lock-screen art (transparent PNG)
├── preview-unlock.png       thumbnail for Style > Unlock
├── keyboard.rgb             six hex digits for RGB keyboards
├── btop.theme               hand-written, overrides the generated file
├── chromium.theme
├── helix.toml
├── shell.toml               replaces the whole generated shell config
├── shell.bar.toml           …or replace just the [bar] section
├── README.md
└── LICENSE

File reference

What an installed theme may not ship

A theme you write by hand is yours, and Omarchy stages all of it. A theme cloned from someone else’s repository is held to a shorter list: installing a theme should change what your desktop looks like, never what it runs.

From a cloned theme, Omarchy drops:

• Any *.lua file. Hyprland loads a theme’s hyprland.lua and gum_env.lua at login, and Neovim loads neovim.lua at startup.
• alacritty.toml, foot.ini, ghostty.conf and kitty.conf. Each one names the program the terminal launches.
• vscode.json, which names an extension to install — and a VS Code extension is arbitrary JavaScript.
• Every symlink, at any depth, because in a cloned theme it points wherever the theme author chose.

Everything that is colour is kept exactly as you wrote it, including files Omarchy would otherwise have generated. Anything dropped is regenerated from your colors.toml and named on stderr, so nothing fails silently. Omarchy tells a cloned theme from a hand-written one by the .git directory that omarchy theme install leaves behind.

Design around this rather than against it. If your theme only looks right with a custom hyprland.lua, it will not look right for anyone who installs it.

A theme older than colors.toml is not left without a palette: its alacritty.toml is converted to a palette in a scratch directory, and only the resulting colors.toml is staged.

Theming an application Omarchy does not cover

Templates belong to the user, not to the theme — a cloned theme cannot install one. If you use an application Omarchy does not theme, drop a file in ~/.config/omarchy/themed/ named after the config it produces, plus a .tpl extension, and write the config with palette placeholders.

gui:
  theme:
    activeBorderColor: ["{{ accent }}", bold]
    inactiveBorderColor: ["{{ muted }}"]
    selectedLineBgColor: ["{{ selection }}"]

The file is regenerated on every theme switch. Your templates are processed before Omarchy’s, so naming one after a built-in output also overrides how that application is themed. There is a fully commented alacritty.toml.tpl.sample in that directory listing every variable available.

A complete palette

This is the shape every bundled theme uses: mode first, then the accents, then backgrounds darkest to lightest, then foregrounds, then the named colours. Nothing is nested; colors.toml has no tables.

mode = "dark"

accent = "#7aa2f7"
selection = "#292e42"
muted = "#414868"

background = "#1a1b26"
dark_background = "#13141c"
darker_background = "#0e0e14"
lighter_background = "#24283b"

foreground = "#a9b1d6"
dark_foreground = "#565f89"
light_foreground = "#b4bee6"
bright_foreground = "#c0caf5"

red = "#f7768e"
yellow = "#e0af68"
orange = "#eb927b"
green = "#9ece6a"
cyan = "#449dab"
blue = "#7aa2f7"
magenta = "#ad8ee6"
brown = "#75493d"

bright_red = "#ff7a93"
bright_yellow = "#ff9e64"
bright_green = "#b9f27c"
bright_cyan = "#0db9d7"
bright_blue = "#7da6ff"
bright_magenta = "#bb9af7"

What each key is for

How light and dark are decided

Omarchy takes the first answer it finds, in this order:

1. The mode key.
2. The legacy theme_type key.
3. A light.mode file next to colors.toml, whatever it contains.
4. Luminance: the three channel bytes of background are summed, and a total above 382 is treated as light.
5. Failing all of that, dark.

Set mode explicitly. Auto-detection is a safety net for old themes, and a mid-tone background sits close enough to the 382 threshold to be guessed wrong.

What Omarchy fills in for you

A short palette still produces a complete theme. When a key is absent, Omarchy derives it:

The derived shades are arithmetic, not taste. They are a reasonable floor, not a substitute for choosing the values yourself — and on a light theme, mixing background toward black for dark_background is very often not what you want.

Legacy and ANSI names

Older themes and templates use short names and numbered ANSI colours. Both still work in either direction, and canonical names win when a theme defines both forms.

color0 through color15 map onto the semantic names — color0 is background, color1 is red, color8 is muted, color15 is bright_foreground — and purple is accepted as a synonym for magenta. Write the canonical names in a new theme; read the legacy ones when you are porting somebody else’s.

Template placeholders

Anything in colors.toml is available to a template as {{ key }}. Two modifiers cover applications that want a different format, and every resolved key supports both.

mix, mix_strip and mix_rgb blend two palette keys by a fraction or a percentage — {{ mix background foreground 15% }}, {{ mix_strip background accent 0.35 }}.

Some keys may hold a Hyprland-style gradient instead of a single colour, such as hyprland_active_border = "rgba(33ccffee) rgba(00ff99ee) 45deg". Three helpers format them, and each takes a fallback key as its second argument: {{ hypr_gradient … }} for Hyprland’s Lua config, {{ shell_gradient … }} for shell border tokens, and {{ gradient_start … }} for consumers that accept one flat colour.

Seven steps

1. Copy a bundled theme whose mode matches what you are making. cp -r "$OMARCHY_PATH/themes/tokyo-night" ~/.config/omarchy/themes/yourname for a dark theme, or flexoki-light for a light one.
2. Delete what you are not keeping: the previous theme’s backgrounds/, preview.png, unlock.png and any hand-written application files. Keep colors.toml.
3. Set mode first, then background, foreground and accent. Those three carry most of the character.
4. Fill in the neutral ramp and the sixteen ANSI colours. Palette best practices covers what to aim for.
5. Add at least one wallpaper under backgrounds/. See backgrounds for sizes and licensing.
6. Apply it with omarchy theme set yourname and live with it for a day. Read code in it, read a long document in it, look at it at night.
7. Turn it into a Git repository and publish.

Prefer a visual editor? The Theme Studio does the same work in the browser, shows contrast ratios while you pick, previews against a simulated desktop, and exports a complete repository.

A complete minimal repository

This is a publishable theme. Four files, nothing generated, nothing that gets dropped on install.

omarchy-harbor-theme/
├── colors.toml
├── backgrounds/
│   └── 001-harbor-dusk.jpg
├── README.md
└── LICENSE

The directory name matters: omarchy-harbor-theme installs as harbor, because Omarchy strips a leading omarchy- and a trailing -theme and lowercases the rest.

A full example colors.toml

An original dark palette, written for this guide. Copy it, change the hexes, keep the structure. The comments are legal TOML and Omarchy skips them.

# Harbor — a cold, slightly green dark theme.
mode = "dark"

# The colour the theme is remembered by.
accent = "#4fa3a5"
selection = "#243b42"
muted = "#5d7480"

# Surfaces, from the primary one outward.
background = "#101a1f"
dark_background = "#0c1418"
darker_background = "#070d10"
lighter_background = "#182831"

# Text, from primary to brightest.
foreground = "#c2d2d8"
dark_foreground = "#7d929c"
light_foreground = "#d7e3e8"
bright_foreground = "#f0f6f8"

# The sixteen ANSI colours, by name.
red = "#e0687a"
yellow = "#d7a75c"
orange = "#dd8a5a"
green = "#7fb069"
cyan = "#4fa3a5"
blue = "#5b8fc9"
magenta = "#a887c9"
brown = "#6e4a33"

bright_red = "#f0899a"
bright_yellow = "#efc27e"
bright_green = "#9bc98a"
bright_cyan = "#72c3c4"
bright_blue = "#82aede"
bright_magenta = "#c3a6e0"

Test it before you publish

• omarchy theme set yourname applies it. omarchy theme list confirms Omarchy can see it.
• omarchy theme current prints what is active.
• omarchy dev theme-preview yourname shows the resolved ramp, including the shades Omarchy derived rather than the ones you wrote.
• omarchy theme color --file ~/.config/omarchy/themes/yourname/colors.toml --all prints every key after fallbacks are applied — the fastest way to find a colour you thought you set and did not.
• Test the install path too. Push the repository and run omarchy theme install <url> on a machine that does not already have it, so you see the theme the way other people will.

Want to try somebody else’s theme without committing to it? Open any theme in this gallery and choose “Try on my computer”. The palette previews for 90 seconds and rolls back on its own unless you keep it.

Contrast first

A theme is a reading surface for eight hours a day. Contrast is not an accessibility checkbox here; it is whether the theme is usable.

• foreground against background: aim for 7:1, treat 4.5:1 as the floor. This is the ratio the Theme Studio enforces on generated palettes.
• dark_foreground against background: at least 4.5:1. Secondary text is still text. Comments below 3:1 are the single most common flaw in community themes.
• accent against background: at least 3:1, and more if the accent ever carries text rather than just a border.
• Every ANSI colour against background: at least 4.5:1. They are syntax highlighting, and a blue that vanishes into a dark background makes code unreadable.
• bright_foreground against selection: at least 4.5:1, because that is the selected-text pairing Omarchy derives.

Measure, do not guess. The Theme Studio reports live ratios for every pair as you edit.

Build the neutral ramp deliberately

The neutral ramp runs from background to bright_foreground. On a dark theme it should read darkest to lightest; on a light theme, lightest to darkest. Seven steps, in this order:

darker_background  →  dark_background  →  background  →  lighter_background
                                        ↓
     dark_foreground  →  foreground  →  light_foreground  →  bright_foreground

• Keep the steps even. A ramp that jumps from one surface to the next and then barely moves looks broken in a card-heavy interface.
• Tint the neutrals. Pure greys next to a saturated accent look dead; carrying a few degrees of the accent’s hue through the ramp is what makes a theme feel designed.
• Do not let lighter_background collide with selection. Both appear behind text, and if they match, selection becomes invisible.
• Leave real distance between background and dark_background. Recessed surfaces that are one or two percent apart read as a rendering artefact.

The sixteen ANSI colours

These are not decoration. They are the terminal, and through it every TUI, diff and syntax highlighter you use.

• Keep the semantics. Red must read as error, green as success, yellow as warning. A green that is actually teal makes git diff lie to you.
• Red and green must be separable for colour-blind users. Differ in lightness as well as hue — do not rely on the hue alone to carry the meaning.
• Make the bright_* variants visibly brighter, not just more saturated. The default derivation mixes 20% toward white; if you write them yourself, at least match that.
• Do not reuse the exact same hex for a colour and its bright variant unless you mean to lose the distinction — some light themes reasonably do, but it flattens bold text in the terminal.
• Check them together, not one at a time. Print a colour table in the terminal and look for two that are hard to tell apart.

Choosing an accent

• Pick one accent and commit. It appears on focused window borders, the active bar element, selected menu rows and links; a second competing accent just reads as noise.
• It usually matches one of your ANSI colours — most bundled themes set accent to the same value as blue or cyan. That is a feature: it keeps the terminal and the desktop consistent.
• It must survive being a thin one-pixel border on a large surface. Very dark or very desaturated accents disappear at that size.
• It must not be so loud that a focused window is uncomfortable to sit in front of. Saturated pure red or pure magenta rarely survive a full day.

Light themes need different thinking

A light theme is not a dark theme with the ends swapped. The most common mistake is taking a dark palette’s ANSI colours unchanged.

• Set mode = "light". Nothing else makes applications pick their light variants reliably.
• Darken and desaturate the ANSI colours. A yellow that is legible on #1a1b26 is invisible on #fffcf0; bundled light themes routinely drop lightness by a third.
• The bright_* colours often cannot be brighter, because brighter means closer to the background. Look at flexoki-light, which sets several of them identical to their base colour and brightens only where it helps.
• Remember that Omarchy’s automatic derivation mixes toward black for dark_background and toward white for the bright colours. Neither rule is right for a light theme, so write those keys explicitly.
• Avoid a pure white background. An off-white such as #fffcf0 or #faf4ed is markedly easier to read for a full day.

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.

Naming the repository

Follow the omarchy-<name>-theme convention. Omarchy takes the last path segment of the clone URL, strips .git, removes a leading omarchy- and a trailing -theme, and lowercases what is left. That remainder becomes both the directory name and the name in the theme picker.

Because the result becomes a directory name that Omarchy passes around, it is validated rather than sanitised. The first character must be a letter, a digit or an underscore; the rest may be letters, digits, ., _, + and -. Capitals are lowercased for you. Anything else — a space, a quote, an accented character — is refused at install time with an error, not turned into a directory.

The install command

omarchy theme install https://github.com/you/omarchy-harbor-theme.git

Omarchy checks the URL names a repository rather than a Git transport helper, clones it into ~/.config/omarchy/themes/harbor, and applies it immediately. SSH URLs work too. If a theme of that name is already installed, it is replaced. The same thing is available from the menu under Install > Style > Theme.

This is also how every theme in this gallery installs, including palettes published from the Theme Studio — those are served as small read-only Git repositories, so the native installer handles them with no account and no extra tooling.

Before you publish

• A README.md with a screenshot, what the theme is for, and background credits.
• A LICENSE, and a note if the backgrounds are licensed differently from the palette.
• A preview.png, so the theme picker shows something.
• No .lua, no terminal configs, no vscode.json — they are dropped on install, so a theme that depends on them is broken for everyone but you.
• A real install test from the published URL on a machine that has never had the theme.

Getting listed on omarchy.org

Omarchy’s own extra themes page ↗ is maintained in the website repository. To be added, send a pull request to omacom/omarchy-site ↗. Listings there carry a screenshot and a link to your repository.

How this gallery imports themes

This gallery is independent of Omarchy and imports from the official listing. For each theme it pins the repository to a specific commit, reads colors.toml as data — or derives a palette from a legacy terminal config — caches the published screenshot and any backgrounds, and records the source URL, commit and licence metadata as provenance. Repository code is never cloned, evaluated or run.

You can also submit a public GitHub repository directly from the gallery. Submission returns a private receipt link for checking review status. It is not an ownership claim, and the original repository stays the credited source.

Two things follow from that, and both are worth doing before you submit: put colors.toml in the repository root, and make sure your licence is one GitHub recognises, since image publication needs a rights review separate from the palette.

What plugins are

The Omarchy desktop runs as a single long-lived Quickshell process, and nearly everything on screen is a plugin inside it: the bar, the panels that drop from it, the emoji picker, the clipboard manager, the menu, the lock screen, and the background services. First-party plugins ship with Omarchy; anything you add lives in ~/.config/omarchy/plugins/.

A plugin is a directory with a manifest.json and some QML. Its id is namespaced — the omarchy. prefix is reserved for first-party plugins.

When a theme wants a plugin

The line is straightforward. A theme changes colour. A plugin changes behaviour or structure. If what you want is not expressible in colors.toml or shell.toml, you want a plugin.

Plenty of visual ambition is reachable without a plugin: shell.toml covers bar sizing, control states in every interaction state, per-side border widths, gradient borders, corner radius and the typographic scale. Try that first — it installs with your theme and needs no trust from the person installing it.

Where to find and publish plugins

Omarchy has a community plugin marketplace at plugins.omarchy.org ↗. omarchy.org/plugins redirects there. It has a browsable catalogue, a guide to developing a plugin, and instructions for publishing one; the marketplace itself is open source at omacom/omarchy-plugin-marketplace ↗.

If your theme pairs well with a specific plugin, link it from your README rather than bundling it. A theme cannot install a plugin, and it should not try to.

omarchy plugin list                        # what is installed, and what is enabled
omarchy plugin add <git-url> --enable      # install from a repository
omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather
omarchy plugin clone omarchy.clock         # copy a built-in and modify it
omarchy plugin update                      # fast-forward every git-managed plugin
omarchy plugin remove acme.weather

Plugins are code, themes are not

This distinction is the reason the two are separate. An installed theme is filtered down to colour before it is staged. A plugin is not: it runs as unsandboxed code inside your long-lived shell process, for as long as your session lasts, with everything your user account can reach.

Omarchy says so plainly and asks you to confirm before adding one. It clones files, validates the manifest and flips a setting — it never runs an install hook and never asks for sudo — but that only covers installation. Read a plugin before you enable it, and link plugins from your theme with the same care you would recommend any other program.

These docs are written here

Everything on these pages was written for this gallery and verified against a real Omarchy install running 4.0.0.alpha on September 15, 2026 — the theme scripts in $OMARCHY_PATH/bin/, the bundled themes, the templates in default/themed/, and the technical theming documentation in Omarchy’s source repository.

Omarchy is an independent project, and this gallery is not affiliated with it. Where upstream is the better answer — install instructions, hardware notes, anything outside theming — we link there rather than paraphrase.

Why the manual is not mirrored here

Omarchy’s code and its website are licensed differently, and it matters here.

• omacom/omarchy ↗, the source, is MIT-licensed. Its docs/theming.md may be reused with attribution, and it informed the reference pages here.
• omacom/omarchy-site ↗, which contains the manual, carries no licence file, and omarchy.org’s footer reserves all rights.

So the manual is not reproduced on this site. Its prose is nobody’s to copy without permission, and a paraphrase that tracked it sentence by sentence would be the same thing with extra steps. What is here instead is an independent description of behaviour we verified ourselves, organised for people making a theme, with links to the manual for everything else.

Read upstream

The chapters of Omarchy’s official manual that bear on theming:

• Making your own theme ↗ — upstream’s own guide.
• Themes ↗ — switching, installing and managing themes as a user.
• Backgrounds ↗ — how wallpapers behave on the desktop.
• Shell plugins ↗ — the plugin system in depth.
• The top bar ↗ — bar layout and widget placement.
• Branding ↗ and common tweaks ↗ — the customisation around a theme.
• Omarchy CLI ↗ — every omarchy subcommand.
• docs/theming.md ↗ — the MIT-licensed technical reference in the source repository.
• Extra themes ↗ and plugins.omarchy.org ↗ — the official listings.

Omarchy changes quickly. If something here disagrees with your machine, your machine is right — and we would like to know.