command not found: xdg-terminal-exec

You pressed Super + Return and nothing happened. Or a menu entry flashed an error naming xdg-terminal-exec. Either way, your config is calling a program that is not on disk. This is almost always an omarchy-update run that stopped partway.

Checked against the source snapshots for v3.8.4, v4.0.0 and v4.0.4, plus the issue and discussion threads listed below.

The fix

1. Get a shell. On 4.x, Super + Space opens the Omarchy menu and Super + Alt + Space opens the Apps menu; try launching Foot, Ghostty, Alacritty or Kitty from there. On 3.x, use Walker. If no launcher responds, switch to a text console with Ctrl + Alt + F2 and log in there. Dropping to a TTY is what ryanrhughes recommended in the accepted answer on discussion #3112, written there as ctrl + alt + 2.

2. Install the missing package.

sudo pacman -S --needed xdg-terminal-exec

The discussion answer suggests pacman -Sy xdg-terminal-exec. Prefer the form above. A bare -Sy refreshes the database without upgrading and can leave you in a partial-upgrade state on Arch. If you have a working shell with the Omarchy tools on PATH, omarchy pkg add xdg-terminal-exec does the same thing (it wraps pacman -S --noconfirm --needed).

3. Finish the update that failed. Installing the package alone is not enough, because the migrations that rewrite your config did not run either.

omarchy-update

If the update itself is what is broken, run the migrations on their own first. lypanov reported in discussion #3380 that omarchy-migrate restored the missing command, after which the update completed. See omarchy-update fails or hangs and migration failed mid-update.

4. On 3.x only, check your Hyprland bindings. Open ~/.config/hypr/bindings.conf and confirm these two lines exist:

$terminal = uwsm-app -- xdg-terminal-exec
bindd = SUPER, RETURN, Terminal, exec, $terminal --dir="$(omarchy-cmd-terminal-cwd)"

jelenv posted these two lines on issue #3200, dexterhere04 restated them the next day, and dhh confirmed that as the correct fix. Two details matter: the flag is --dir, not --working-directory (the v3.1.5 migration renamed it), and, as jelenv pointed out, the quotes around the command substitution are required for paths with spaces.

5. On 4.x, do not edit a bindings.conf. Quattro moved Hyprland config to Lua. The binding lives in default/hypr/bindings/applications.lua as o.bind("SUPER + RETURN", "Terminal", { omarchy = "terminal" }), which runs omarchy-launch-terminal. That script is a one-liner that execs setsid uwsm-app -- xdg-terminal-exec --dir="$(omarchy-cmd-terminal-cwd)". Run omarchy-launch-terminal by hand to see the real error. See the conf to Lua migration reference.

Verify it worked

command -v xdg-terminal-exec        # should print a path
pacman -Q xdg-terminal-exec         # should print a version
omarchy-default-terminal            # should print foot, ghostty, alacritty or kitty
omarchy-migrate --pending           # should list nothing

Then press Super + Return. If omarchy-default-terminal prints a raw .desktop id or nothing, your ~/.config/xdg-terminals.list points at a terminal that is not installed. Fix it with omarchy default terminal foot, since Foot ships in the base package list on 4.0.4 and is always present.

Why it happens

Omarchy v3.1.5 (2025-11-03) switched terminal launching to xdg-terminal-exec. The release notes describe it as making sure you cannot end up without a working terminal. TERMINAL became xdg-terminal-exec, the Hyprland binding stopped calling $TERMINAL directly, and migration 1762121828 installed the package and then rewrote bindings.conf, uwsm/default and the Waybar config.

omarchy-update pulls the new checkout before it runs migrations, and that checkout’s scripts and defaults already call xdg-terminal-exec. The package itself only arrives when the migration runs. If the update stops before that, for example on a dependency conflict, you are left with new files referencing a binary you do not have. ryanrhughes described this in the accepted answer on discussion #3112, and lypanov saw exactly that state in discussion #3380: repo up to date, no migrations run, no packages updated. The reports cluster on the v3.1.5 release day and the week after it: issues #3200, #3250 and discussions #3112, #3120 and #3380 are all the same failure.

The design has not changed in 4.x. xdg-terminal-exec is still in install/omarchy-base.packages and TERMINAL=xdg-terminal-exec is still exported by the session defaults in v4.0.4. So the same interrupted update produces the same missing binary. What changed is the recovery: there is no bindings.conf to patch, and the terminal preference file moved from ~/.config/xdg-terminals.list to /usr/share/xdg-terminal-exec/hyprland-xdg-terminals.list for the stock case.

If that did not work

If the binary is present but no terminal opens, you have a different problem with the same symptom. Three are open against 4.x as of 2026-09-16.

Your default terminal silently reverted after the Quattro upgrade. JoshJAL showed in issue #11632 that omarchy-upgrade-to-quattro deletes ~/.config/xdg-terminals.list when its sha256 matches a known stock default. Because omarchy-default-terminal writes a fixed template, a deliberately chosen Ghostty produces a byte-identical file and gets retired, so the system default (Foot) wins. The two hashes on the retire list are the Ghostty and Alacritty templates, so a chosen Alacritty is lost the same way. Re-run omarchy default terminal ghostty after upgrading. More context at 3 to 4 Quattro.

Your terminals list points at something you never installed. In issue #9356, ozz1ee-dev reported that omarchy install terminal ghostty on Omarchy 4.0.1 for aarch64 rewrites ~/.config/xdg-terminals.list even though the package is not available and never gets installed. The omarchy-pkg-add in the v4.0.4 snapshot exits non-zero when a package did not install, which should stop omarchy-install-terminal from touching the list, but the issue is still open. Check with pacman -Q ghostty before trusting the list.

Your theme broke Foot. Issue #7105 documents a theme with no colors.toml producing no foot.ini, which Foot treats as a fatal config error. Alacritty and Kitty have the same unguarded include; Ghostty does not. Recover from a TTY with omarchy theme set tokyo-night.

You see error: unexpected argument '-e' found. In discussion #3380, MananDesai54 hit this after installing the package by hand. The usage text under the error is Warp’s, so xdg-terminal-exec was resolving to a terminal that does not accept -e. Reset to a supported terminal with omarchy default terminal foot and re-run the update.

Related

• omarchy-update fails or hangs
• Migration failed mid-update
• Stuck at TTY or cannot switch TTY
• Custom keybindings lost after Quattro
• omarchy-default-terminal
• Omarchy manual: Terminal