omarchy-zsh on Omarchy

omarchy-zsh: How to use Omarchy’s Zsh setup (install, keybindings, aliases)

omarchy-zsh is Omarchy’s zero-config Zsh — it layers the distro’s shared shell config (aliases, functions, env, tool inits) onto Zsh plus fzf-powered keybindings, so you get Omarchy’s terminal experience in a better shell without hand-editing dotfiles.

TL;DR install

# Install the package (omarchy pkg add is the distro's pacman wrapper)
omarchy pkg add omarchy-zsh

# Set up zsh (keeps bash as the login shell; zsh auto-launches from it)
omarchy-setup-zsh

Open a new terminal (Super+Enter). You’re now in zsh with Omarchy’s config.

Getting started in 5 minutes

1. The fzf keybindings you’ll actually use daily

These come from the package’s zsh-specific config (documented in the repo README):

Ctrl+R alone will change how you feel about the terminal. Type a fragment of a command you ran three days ago, hit Ctrl+R, pick it.

2. The aliases worth knowing (from omadots)

Shared config is pulled from the omadots dotfiles project at package build time and sourced from /usr/share/omarchy-zsh/shell/, so package updates apply immediately. The key aliases to learn (same set Omarchy ships for bash, syntax-compatible with zsh):

• ls → eza with icons, dirs-first; lt → eza tree (level 2, git status); lsa / lta are their -a variants
• .., ..., .... → up one, two, three directories
• g → git; gcm → git commit -m; gcam → git commit -a -m; gcad → git commit -a --amend
• d → docker; r → rails; ff → fzf with a bat preview of each file
• open → xdg-open; n → nvim (opens current dir with no args)
• cc / cdx → Claude Code / Codex; ccx / cdxx → the same with permission checks bypassed (intentional — the x suffix means dangerous mode)
• z → zoxide smart-jump (the cd function itself is zoxide-backed)

3. Where your personal config goes

nvim ~/.zshrc

omarchy-setup-zsh generates your ~/.zshrc as a small loader. Add your own config at the bottom, after the omarchy-zsh loading — user customizations there take precedence over system defaults. This is the designed split: the package owns /usr/share/omarchy-zsh/; you own ~/.zshrc; updates never touch your file.

Shell functions are also shared with Omarchy’s bash defaults and documented in the Omarchy manual’s shell-functions page: compress/decompress, iso2sd, format-drive, tmux dev layouts (tdl, tds, tdlm, tsl — tdl c opens a layout with your editor + opencode + terminal), ga/gd for git worktrees, rsw/lsw/dsw rsync watchers, and fip/dip/lip SSH port forwards.

Common issues & fixes

You ran chsh -s /usr/bin/zsh and now things break — or nothing works after reboot

Fix: That’s the known trap on Omarchy: the display manager and session init chain expect bash, so a zsh login shell breaks session startup (basecamp/omarchy discussion #2495 documents the whole chain; one user reports the black-screen-after-decrypt symptom). Fix: chsh -s /usr/bin/bash to restore bash, then use the supported flow — install the package and run omarchy-setup-zsh, which auto-launches zsh from bash instead.

You want to remove starship, but pacman refuses

Fix: This is a real open issue on the omarchy-zsh tracker (“Support to turn starship off”): starship is a hard package dependency because the prompt init lives in the shared inits file. Until the maintainer makes it optional, the workarounds are: edit your ~/.zshrc to neutralize the prompt (e.g. don’t source the starship init, or set STARSHIP_CONFIG to a minimal config — your ~/.zshrc runs last so it wins), or use STARSHIP env overrides rather than uninstalling.

Your own ~/.zshrc additions (or another dotfiles framework) die silently

Fix: zsh expands aliases at parse time, so if your rc defines a function whose name is already a live alias (omarchy-zsh defines single-letter aliases like c and cy), that’s a parse error and zsh abandons the rest of the file (documented real-world case, measured at line 470 of a ~/.zshrc). Fix: don’t define functions named after omarchy aliases; if a framework defines them, escape the name (\cy() { ... }) to suppress alias expansion.

Double prompts, doubled-up completions, or hooks firing twice after layering oh-my-zsh or another rc on top

Fix: omarchy-zsh’s inits initializes starship, zoxide, mise, and fzf. If your rc initializes them again, you get duplicate precmd hooks and two inits for one prompt (same source). Either let omarchy-zsh own those inits (it’s already doing them) or skip them in your ~/.zshrc. Same goes for zsh-syntax-highlighting: the package sources it last by design, so don’t source it twice.

Completions for omarchy subcommands feel thin

Fix: This was a real gap fixed by PR omacom/omarchy-zsh#10, which brought the zsh _omarchy completion in line with the bash completer (arg enums, alternatives, file fallback). Update the package (omarchy pkg add omarchy-zsh on an already-installed package, or sudo pacman -Syu omarchy-zsh) and open a new shell. The completer ships to /usr/share/zsh/site-functions/_omarchy, so it works even in a custom ~/.zshrc that never ran omarchy-setup-zsh, as long as compinit runs.

Pairs well with / If you hate this, try

Pairs well with

• omarchy-nvim (Omarchy’s editor config — EDITOR=nvim is already set for you), fzf and zoxide (their keybindings/inits are wired in automatically), starship (the default prompt), tmux (the tdl/tds dev-layout functions), eza + bat (the ls/lt/ff aliases assume them).

If you hate this, try

• Stay on Omarchy’s bash defaults — same aliases and functions, zero setup. Want a different shell philosophy: omarchy-fish is the sibling package for Fish. Want the plugin ecosystem: oh-my-zsh works on Omarchy, but see the parse-conflict and double-init issues above before stacking it on top of omarchy-zsh.

Comparison

One-line verdict: if you’re on Omarchy and want Zsh, install omarchy-zsh — it’s the only Zsh option built to carry Omarchy’s exact shell config, and it’s the only one that keeps your session boot chain intact.