OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-core low occasional DISPUTE

A script that shadows an omarchy command works over ssh but never runs from the desktop

omarchyhyprlandpathcustomization
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

Cause confirmed on 4.0.4-1. /usr/share/omarchy/default/hypr/envs.lua lines 30-36 strip $OMARCHY_PATH/bin, re-insert it at position 1 and hl.env("PATH", ...). A desktop terminal's PATH here has /usr/share/omarchy/bin ahead of /usr/local/bin. /usr/share/omarchy/bin holds 441 entries, symlinks to /usr/bin/omarchy-* (445 there). /etc/security/pam_env.conf line 76 and env-bootstrap are as quoted, and env-bootstrap prepends the bin dir only in dev-link mode. ~/.config/hypr/hyprland.lua requires default.hypr.omarchy before user code, so a line at the end runs after envs.lua. Three fix defects: (1) mv /usr/local/bin/omarchy-<name> ~/... fails without root, since /usr/local/bin is root-owned. Corrected to copy and then remove with sudo. (2) The binding instruction names raw hl.bind/hl.dsp.exec_cmd, but the user's bindings.lua uses Omarchy's o.bind(keys, description, command) helper (/usr/share/omarchy/default/hypr/helpers.lua:92, which wraps those two). A concrete line is given. (3) A copy into ~/.local/omarchy-overrides/bin needs to be executable. Cited https://wiki.hypr.land/Configuring/Environment-variables/ returns 404 (curl 2026-10-05). The page is https://wiki.hypr.land/configuring/core/environment-variables/ (200, source content/configuring/core/environment-variables.md documents hl.env and os.getenv). Whether os.getenv sees envs.lua's hl.env value is still unconfirmed and the record already says so. I did not probe it, because that would mean reloading the operator's session.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.
RISK

A shadowed omarchy command is no longer updated by omarchy update. When upstream changes the stock script, your copy keeps the old behaviour, and other Omarchy scripts that call it by name will run your copy.

Symptom

I copied an Omarchy command to /usr/local/bin/omarchy-<name> (or ~/.local/bin/omarchy-<name>) and edited it. From ssh or a TTY my version runs. From a terminal opened in Hyprland, from a keybinding, or from the Omarchy menu, the stock version still runs and my change has no effect. which omarchy-<name> in a desktop terminal prints /usr/share/omarchy/bin/omarchy-<name>. A copy in ~/.local/bin is never used anywhere.

Cause

Omarchy 4's Hyprland config puts the Omarchy bin directory first on the session's PATH. /usr/share/omarchy/default/hypr/envs.lua (lines 30 to 36 on 4.0.4-1) removes $OMARCHY_PATH/bin from wherever it is in PATH, inserts it at position 1, and exports the result with hl.env("PATH", ...). Every process Hyprland starts, including terminals, keybindings and the menu, inherits a PATH that begins with /usr/share/omarchy/bin, ahead of /usr/local/bin. On 4.0.4 that directory holds a symlink for almost every omarchy-* command (pointing at /usr/bin/omarchy-*), so the stock command wins.

Outside the desktop the order is different. /etc/security/pam_env.conf sets PATH DEFAULT=/usr/local/sbin:/usr/local/bin:/usr/bin:@{HOME}/.local/share/mise/shims:@{HOME}/.local/bin, and /usr/share/omarchy/default/bash/env-bootstrap only prepends the Omarchy bin directory when OMARCHY_PATH is not /usr/share/omarchy (a dev link). So over ssh /usr/local/bin comes before /usr/bin and an override there works. ~/.local/bin is appended after /usr/bin by both PAM and env-bootstrap, so a copy there loses to /usr/bin/omarchy-* in every context.

Fix

**Recommended:** do not shadow the stock name. Give your script its own name and bind that, so an Omarchy update can never silently bypass it:


install -Dm755 /usr/bin/omarchy-<name> ~/.local/bin/my-<name>
$EDITOR ~/.local/bin/my-<name>

Then add a binding in ~/.config/hypr/bindings.lua with Omarchy's helper, the same form as the examples in that file (unbind the default first if you are replacing one):


hl.unbind("SUPER + SHIFT + X")
o.bind("SUPER + SHIFT + X", "My <name>", "my-<name>")

Menu entries and other Omarchy scripts still call the stock name, so this only covers bindings you control.

**If you must shadow the name for the whole desktop session,** use a dedicated directory that holds only your overrides, and put it first after Omarchy's defaults have loaded. Add this at the end of ~/.config/hypr/hyprland.lua, which runs after require("default.hypr.omarchy"):


hl.env("PATH", os.getenv("HOME") .. "/.local/omarchy-overrides/bin:" .. (os.getenv("PATH") or "/usr/local/bin:/usr/bin"))

mkdir -p ~/.local/omarchy-overrides/bin
install -m755 /usr/local/bin/omarchy-<name> ~/.local/omarchy-overrides/bin/
sudo rm /usr/local/bin/omarchy-<name>    # optional, keeps one copy to maintain

Log out and back in so every process starts from the new environment. Keep ~/.local/bin itself out of that line: it holds the mise wrappers, and moving it ahead of mise's own directories is what makes them exec-loop (upstream #13040).

Whether os.getenv("PATH") at that point already reflects the hl.env call in envs.lua has not been confirmed, so check the result with the verify step rather than assuming it.

**Plain Arch with your own Hyprland config:** nothing reorders PATH for you, and an override in /usr/local/bin wins as usual.

Verify

Open a new terminal from the desktop and run:


echo "$PATH" | tr ':' '\n' | head -3
command -v omarchy-<name>

The override directory should be first and command -v should print your copy. Trigger the binding or menu entry and confirm your change takes effect.

Sources

local-bin-override-ignored-from-desktop