You install the OpenAI Codex CLI, open a new terminal, type codex—and zsh throws this back at you:
zsh: command not found: codex
This error is almost never a broken installation. It simply means your shell can’t find an executable named codex in any directory listed in your PATH. There are a handful of reasons that happens, and each has a quick fix.
Table of Contents
Why this error happens
When you type a command, zsh searches every directory in your PATH variable for a matching program. If it doesn’t find one, you get command not found. So there are only two possibilities:
codexisn’t installed (or the install failed partway).codexis installed, but its folder isn’t in yourPATH.
For background on how the search works, see what is the PATH variable in Linux and how it works and the general guide to fixing “command not found”.
Did you install from a .dmg file? Read this first
If you downloaded a .dmg, you installed the desktop app—and this is the most common source of confusion:
Installing a Mac app does not create a terminal command. The
.appbundle lives in/Applications, which is not on yourPATH, so zsh has no idea whatcodexmeans.
The GUI app and the codex terminal command are two separate things. Here’s how to get the command working.
1. Finish installing the app
Open the disk image and drag the app into Applications, then confirm it landed:
open ~/Downloads/Codex*.dmg
ls -d /Applications/*[Cc]odex*
/Applications/Codex.app
If macOS blocks the app on first launch, clear the quarantine flag:
xattr -dr com.apple.quarantine /Applications/Codex.app
2. Check the app for a built-in “install CLI” option
Many desktop apps ship a command-line helper and install it for you. Open the app and look in its menu bar or settings for an entry such as “Install command line tool”, “Install codex command in PATH”, or a CLI/Terminal section in Preferences. (VS Code’s Shell Command: Install ‘code’ command is the classic example of this pattern.)
See also: Mastering the Linux Command Line — Your Complete Free Training Guide
If that option exists, use it—it’s the cleanest route. Then reload your shell:
source ~/.zshrc
codex --version
3. Or link the binary inside the app bundle
If the app has no such option, look for an executable inside the bundle. A .app is just a folder, so you can search it:
ls -l /Applications/Codex.app/Contents/MacOS/
total 178208
-rwxr-xr-x 1 root wheel 91234567 Sep 8 10:20 Codex
To search the whole bundle for anything CLI-like:
find /Applications/Codex.app -type f -perm -111 -iname '*codex*'
/Applications/Codex.app/Contents/MacOS/Codex
/Applications/Codex.app/Contents/Resources/app/bin/codex
If you find a dedicated CLI binary (often under Contents/Resources/.../bin/), symlink it into a directory on your PATH:
sudo ln -s "/Applications/Codex.app/Contents/Resources/app/bin/codex" /usr/local/bin/codex
Then verify:
which codex
codex --version
/usr/local/bin/codex
codex 0.5.1
Note: don’t symlink the main GUI executable in
Contents/MacOS/unless it genuinely accepts command-line arguments—launching a windowed app from the terminal usually won’t behave like a CLI.
4. Simplest reliable option: install the CLI itself
If the app doesn’t include a command-line tool, install the Codex CLI separately. The two can coexist happily:
npm install -g @openai/codex
codex --version
This is the most dependable way to get a working codex command in zsh, and it’s covered in detail in the steps below.
Did you download a standalone binary (not a .dmg)?
If you downloaded a raw macOS binary or archive (rather than a .dmg, npm, or Homebrew), this error is expected—downloading a file does not install it. The binary is sitting in your Downloads folder, which is not in your PATH, and macOS has flagged it as quarantined. Here’s the full fix.
1. Extract the archive (if needed)
Downloads usually arrive as a .zip or .tar.gz. Move into your Downloads folder and unpack it:
cd ~/Downloads
# For a .zip file
unzip codex-*.zip
# For a .tar.gz file
tar -xzf codex-*.tar.gz
List what you got (the exact file name varies by release and CPU type):
ls -l ~/Downloads | grep -i codex
-rw-r--r--@ 1 user staff 28451234 Sep 8 10:15 codex-aarch64-apple-darwin.tar.gz
-rwxr-xr-x@ 1 user staff 71203344 Sep 8 10:16 codex
2. Confirm you have the right build for your Mac
An Intel binary won’t run on Apple Silicon and vice versa. Check your Mac:
uname -m
arm64
arm64 means Apple Silicon (M1/M2/M3/M4) — you want the aarch64/arm64 build. x86_64 means an Intel Mac. Now check the file you downloaded:
file ~/Downloads/codex
/Users/you/Downloads/codex: Mach-O 64-bit executable arm64
If these don’t match, re-download the correct build.
3. Make it executable
A downloaded file often lacks the execute permission:
chmod +x ~/Downloads/codex
Without this you’d see zsh: permission denied: ./codex instead.
4. Remove the macOS quarantine flag
macOS Gatekeeper tags anything downloaded from the internet. If you skip this, you’ll get “codex cannot be opened because the developer cannot be verified.” Clear the flag:
xattr -d com.apple.quarantine ~/Downloads/codex
If the file came inside a folder, clear it recursively:
xattr -dr com.apple.quarantine ~/Downloads/codex-folder
You can confirm the attribute is gone:
xattr ~/Downloads/codex
No output means it’s clean.
5. Move it into a directory on your PATH
This is the step that actually fixes command not found. /usr/local/bin is on the default macOS PATH, so move the binary there:
sudo mv ~/Downloads/codex /usr/local/bin/codex
Prefer not to use sudo? Use a folder in your home directory instead, then add it to your PATH:
mkdir -p ~/.local/bin
mv ~/Downloads/codex ~/.local/bin/codex
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
6. Verify
which codex
codex --version
/usr/local/bin/codex
codex 0.5.1
That’s it. If you’d rather not move the file at all, you can always run it by path from its folder—note the leading ./, which tells zsh to look in the current directory instead of searching PATH:
cd ~/Downloads
./codex --version
The sections below cover the npm and Homebrew installation methods.
Step 1: Check whether codex is actually installed
First find out if the binary exists anywhere:
which codex
command -v codex
If both print nothing, the shell truly can’t see it. Next, check whether npm installed it globally:
npm list -g --depth=0
/usr/local/lib
└── @openai/[email protected]
If you see @openai/codex in that list but which codex came up empty, the package is installed and you have a PATH problem—jump to Step 3.
If it’s not listed at all, install it in Step 2.
Step 2: Install (or reinstall) the Codex CLI
The Codex CLI is distributed as an npm package. Install it globally:
npm install -g @openai/codex
On macOS you can also use Homebrew:
brew install codex
Then verify:
codex --version
codex 0.5.1
If the install itself fails with a permissions error (EACCES), don’t reach for sudo npm install -g—that often creates root-owned files that cause this exact problem later. Instead, point npm at a directory you own (see Step 4).
Node.js is required. Check you have it:
node --version
npm --version
If Node is missing, install it first—see how to install a package in Linux.
Step 3: Add the npm global bin directory to your PATH
This is the most common cause. npm installed codex somewhere your shell isn’t looking. Find out where npm puts global binaries:
npm config get prefix
/usr/local
The executables live in that path plus /bin—so /usr/local/bin here. Confirm the file is there:
ls -l $(npm config get prefix)/bin | grep codex
lrwxr-xr-x 1 user admin 38 Sep 8 10:22 codex -> ../lib/node_modules/@openai/codex/bin/codex.js
Now check whether that directory is in your PATH:
echo $PATH
If it’s missing, add it to your zsh config:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
Or write the literal path, which is slightly faster at shell startup:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
For more on export, see the Linux export command.
Step 4: Reload your shell
A PATH change in ~/.zshrc does not apply to terminals that are already open. Reload it:
source ~/.zshrc
Then test again:
codex --version
If it works now, that was your problem. (Opening a brand-new terminal window has the same effect.)
Step 5: Check for an nvm / multiple Node versions issue
If you use nvm, global npm packages are installed per Node version. Switch Node versions and your globally installed codex disappears:
nvm current
v20.11.0
nvm ls
v18.19.0
-> v20.11.0
If you installed codex under v18 but are now running v20, reinstall it for the active version:
npm install -g @openai/codex
To avoid the surprise entirely, set a default Node version:
nvm alias default 20
Step 6: Apple Silicon Macs — check the Homebrew path
If you installed via Homebrew on an Apple Silicon Mac (M1/M2/M3), binaries go to /opt/homebrew/bin, not /usr/local/bin. Older shell configs often miss this:
brew --prefix
/opt/homebrew
Add Homebrew’s environment to zsh:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
Step 7: Fix a permissions problem (EACCES)
If you previously ran sudo npm install -g, npm’s directories may be owned by root, leaving the binary unreadable or unlinked for your user. The clean fix is to give npm a prefix inside your home directory:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex
Now global installs never need sudo, and the binary lands in a directory you control.
Verify the fix
which codex
codex --version
/usr/local/bin/codex
codex 0.5.1
If both commands respond, you’re done.
Quick summary
| Cause | Fix |
|---|---|
Installed the .dmg desktop app | The app is not a CLI—use its “install command line tool” option, symlink the bundled binary, or npm install -g @openai/codex |
Downloaded binary still in ~/Downloads | chmod +x, clear quarantine, move to /usr/local/bin |
| macOS Gatekeeper quarantine | xattr -d com.apple.quarantine codex |
| Wrong CPU build (Intel vs Apple Silicon) | Check uname -m and re-download the matching build |
| Not installed | npm install -g @openai/codex |
| npm bin dir not in PATH | Add $(npm config get prefix)/bin to ~/.zshrc |
.zshrc edited but not reloaded | source ~/.zshrc |
| Switched Node version (nvm) | Reinstall under the active version |
| Homebrew on Apple Silicon | eval "$(/opt/homebrew/bin/brew shellenv)" |
EACCES / sudo-installed | Set npm config set prefix ~/.npm-global |
In almost every case, zsh: command not found: codex is a PATH issue rather than a broken package. Confirm the binary exists with npm list -g --depth=0, make sure its directory is on your PATH, and reload your shell.
