Troubleshooting

codex: command not found after installing

npm finished installing, but your current terminal hasn't reloaded PATH. Open a new terminal and try again.

If it still fails, check that npm's global bin directory is on your PATH:

npm config get prefix
# that directory + /bin must be on $PATH

EACCES: permission denied during npm install

Node was installed with system permissions (common on Linux). Two fixes:

Option 1 — change the npm prefix (quick):

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # add this line to ~/.bashrc or ~/.zshrc

Option 2 — use nvm (recommended long-term):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts

Then re-run the install command.

Windows: running scripts is disabled on this system

Windows PowerShell blocks .ps1 files by default (execution policy Restricted), and typing codex in PowerShell goes through npm's codex.ps1 shim. Open PowerShell and run once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then open a new terminal. (Our install script is not affected — it calls npm through cmd to sidestep this.)

Windows: EBUSY: resource busy or locked

Codex is running (CLI, the VS Code extension or the app), so npm cannot overwrite codex.exe. The current script detects this case: it skips the upgrade and still updates your config — you can keep working right away. To upgrade the CLI itself, close everything running codex and re-run the install command.

Wrong or expired key (401 / unauthorized)

• Check the key in ~/.codex/auth.json is correct and complete (keys start with sk-)
• To switch keys, re-run the install command with the new key — the old config is backed up automatically

Windows: config file has an encoding problem

If you edited the file by hand in PowerShell using Set-Content -Encoding UTF8, PowerShell 5.1 prepends a BOM that breaks Codex's TOML/JSON parsing. Fix: use the install script (writes clean BOM-less files), or save the file in VS Code with UTF-8 encoding (not UTF-8 with BOM).

Restoring an old config

Every script run backs up the previous config next to the new file:

ls ~/.codex/*.bak.*
# restore by copying back, e.g.
cp ~/.codex/config.toml.bak.20260811120000 ~/.codex/config.toml

Still stuck?

Contact support with a screenshot of the error — see the channels on Getting started.