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

Fix `omarchy theme install` refusing a URL, hanging, or eating an existing theme

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

Re-audited against /usr/share/omarchy/bin/omarchy-theme-install and /usr/share/omarchy/bin/omarchy-git-url-check on this workstation at omarchy 4.0.2-1, and against bin/omarchy-theme-install on the quattro branch, which is byte-identical to the installed copy. Most of the record holds. Both refusal strings are exact (names the '$scheme' transport, which Omarchy does not clone from. and names a git option or transport helper, not a repository.), TRANSPORTS=(ssh git git+ssh ssh+git http https ftp ftps file) is exact with ext and fd deliberately excluded, Error: '<url>' does not give a usable theme name. and Error: Failed to clone theme repo. are exact, the rm -rf "$THEME_PATH" really does run before git clone, and the clone has no timeout, no GIT_TERMINAL_PROMPT=0 and inherited stdin, so the hang story holds as read from the script. Every path is Omarchy 4: ~/.config/omarchy/themes, and ~/.local/state/omarchy/current/theme.name which omarchy-theme-set really writes. Nothing points at ~/.local/share/omarchy. omarchy-theme-remove takes an optional name and otherwise shows an omarchy-menu-select picker, omarchy theme refresh and the other subcommands are all present in the dispatcher, and tokyo-night is one of the 22 themes in /usr/share/omarchy/themes. One claim is out of date and is the reason for the correction. The record says the derived name is refused when it is empty, starts with a dot, or contains a slash. That was the rule described in the merged issue 7884, but the shipping script now applies a positive allowlist under a pinned locale, LC_ALL=C with ^[a-z0-9_][a-z0-9._+-]*$, which also refuses a leading -, a space, @, ~ and any non-ASCII letter. A reader hitting the name error on a repo like omarchy-Solarized Light-theme would not be explained by the record's rule, and the fix offered no way to predict the name at all. The cause is rewritten with the real regex and the fix gains a pre-flight block that derives the name and tests it. Current behaviour is better than the record describes in two places, and both are now stated: the name check is stricter and safer, and a failed clone leaves nothing behind. That second point was exercised here rather than assumed, with GIT_TERMINAL_PROMPT=0 git clone -- https://github.com/omacom/definitely-not-a-real-repo-o3.git /tmp/o3clonetest, which exited 128 and left no /tmp/o3clonetest. The destructive pre-clone rm -rf of an existing theme is therefore still the only real loss, and the record's danger already says so correctly. Not exercised: omarchy theme install was never run on this machine, so the refusals, the hang and the theme-name error were read from the script rather than triggered, and no credential or host-key prompt was provoked.

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

omarchy theme install does rm -rf "$THEME_PATH" before it clones, so a clone that then fails leaves you with **no** theme at that name. The name is derived from the URL with omarchy- and -theme stripped, so two unrelated repos can collide on it and quietly replace each other. Back up any hand-edited theme first: cp -a ~/.config/omarchy/themes/<name> ~/theme-backup-<name>. A cloned theme is also arbitrary content from a stranger. Omarchy drops the files that can run code but everything else is applied as-is.

Symptom

omarchy theme install <url> fails in one of several ways. It prints omarchy-git-url-check: '<url>' names the 'sftp' transport, which Omarchy does not clone from. or omarchy-git-url-check: '<url>' names a git option or transport helper, not a repository. and stops. Or it prints Error: '<url>' does not give a usable theme name. Or git runs and fails with fatal: repository '<url>' not found followed by Error: Failed to clone theme repo. Or, the worst one, it just sits there forever with no output, because git is waiting on Username for 'https://github.com': or an SSH host-key prompt you cannot see when the install was launched from the Omarchy menu.

Cause

bin/omarchy-theme-install pre-screens the URL with bin/omarchy-git-url-check before cloning. That refuses anything starting with -, anything matching <helper>::<address> (git's transport-helper shape, and ext:: runs a shell command), and any <scheme>:// whose scheme is not on the allowlist ssh git git+ssh ssh+git http https ftp ftps file. It then derives the theme name from the URL: strip an scp-style user@host: prefix when the URL holds no :// and the part before the first colon holds no slash, then basename -- ... .git, strip a leading omarchy- and a trailing -theme, and lowercase. The derived name is then held to a positive allowlist under a pinned locale rather than to a short list of bad shapes:


if ! (LC_ALL=C; [[ $THEME_NAME =~ ^[a-z0-9_][a-z0-9._+-]*$ ]]); then
  echo "Error: '$REPO_URL' does not give a usable theme name."
  exit 1
fi

So the name must start with a lowercase ASCII letter, a digit or an underscore, and may then contain only those plus ., + and -. A basename carrying a space, @, ~, a second colon, a slash or a non-ASCII letter is refused, and so is an empty name, one starting with . or -, and one that reduces to ... The locale is pinned because a bare [a-z] range follows collation and would otherwise let é through. That strictness is deliberate: the name is joined into a path that is about to be rm -rf'd, and is later passed around by name into menu command lines. Anything that survives goes to git clone -- "$REPO_URL" "$THEME_PATH", where the -- is what stops a dash-leading URL being read as a git option. That clone inherits the terminal's stdin, sets no GIT_TERMINAL_PROMPT=0 and has no timeout, so a private repo over HTTPS prompts for credentials and a first-time SSH host prompts for the host key, and the command blocks forever when it was launched from the Omarchy menu where nothing can answer the prompt. A URL pointing at a GitHub page (.../tree/main) or a tarball is not a repository and git rejects it. And critically, the existing ~/.config/omarchy/themes/<derived-name> is rm -rf'd **before** the clone runs, so a failed install destroys whatever was already there. git itself deletes the destination it created when a clone fails, so there is no half-clone left to tidy up, but the directory that was removed first does not come back.

Fix

Run installs from a terminal, never from the Style > Theme menu, so git's prompts are visible:


omarchy theme install https://github.com/<owner>/omarchy-<name>-theme.git

Pre-flight the URL **and** the theme name it derives, before you let either near your themes directory:


URL='https://github.com/<owner>/omarchy-<name>-theme.git'
omarchy-git-url-check "$URL" && echo 'url shape accepted'
git ls-remote "$URL" >/dev/null && echo 'repo reachable'

# the name Omarchy will derive, and the rule that name has to pass
P="$URL"
[[ $P != *"://"* && $P == *:* && ${P%%:*} != */* ]] && P="${P#*:}"
NAME=$(basename -- "$P" .git | sed -E 's/^omarchy-//; s/-theme$//' | tr '[:upper:]' '[:lower:]')
echo "theme name: $NAME"
(LC_ALL=C; [[ $NAME =~ ^[a-z0-9_][a-z0-9._+-]*$ ]]) && echo 'name accepted' || echo 'name refused'
[[ -d ~/.config/omarchy/themes/$NAME ]] && echo "WARNING: install deletes ~/.config/omarchy/themes/$NAME first"

Accepted URL forms are https://, http://, ssh://, git://, git+ssh://, ssh+git://, ftp://, ftps://, file://, and scp-style git@host:org/repo.git. Copy the repo's **clone** URL, not the page URL. A /tree/main or /releases/download/... link is not a repository. If the name check is what refused you, rename the repo or clone it yourself into ~/.config/omarchy/themes/<a-name-that-passes> and run omarchy theme set <that-name>.

For a private repo, get the credentials working outside Omarchy first:


ssh -T git@github.com          # accepts the host key, proves the key works
git clone git@github.com:<owner>/<repo>.git /tmp/theme-probe && rm -rf /tmp/theme-probe

Clean up a half-installed theme:


omarchy theme remove <name>          # interactive picker if you omit the name
omarchy theme set tokyo-night

Or by hand, if the directory name is not what you expected:


ls -la ~/.config/omarchy/themes/
rm -rf ~/.config/omarchy/themes/<name>

Verify

ls ~/.config/omarchy/themes/<name>/colors.toml exists, cat ~/.local/state/omarchy/current/theme.name names the new theme, and grep -rn '{{' ~/.local/state/omarchy/current/theme/ returns nothing.

Sources

theme-install-refused-or-hangs-on-bad-git-url