Extension field notesUnofficial help

Last updated: ยท Applies to: Codex CLI installation with npm or Homebrew

Codex CLI Install: Installation and Install Error Fixes

Install the Codex CLI with npm install -g @openai/codex or brew install --cask codex. For npm, check that Node.js meets the package requirement. If installation fails, don't use sudo: set npm's global prefix to a user directory. Reinstall Codex when its launcher reports a missing optional dependency.

Install the Codex CLI

Choose an installation command from the pinned README:

npm install -g @openai/codex
brew install --cask codex

For the npm installation, the pinned package metadata declares Node.js >=16.

Codex CLI install errors

Missing optional dependency

Missing optional dependency ${platformPackage}. Reinstall Codex: ${updateCommand}

Source: pinned launcher source. These placeholders represent the platform package and reinstall command. The default reinstall command is npm install -g @openai/codex@latest.

Launcher permission or command lookup failure

permission denied or command not found

Source: issue #9520, reporting bin/codex.js without execute permission. This is a reported launcher problem.

Numbered fixes: CLI

  1. Check the npm requirement

    Check your Node.js version against the package requirement of >=16.

    node --version

  2. Use a user directory for npm global installs

    Don't use sudo. In a macOS or Linux shell, set the npm global prefix to a user directory and add its bin directory to PATH:

    npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

    Keep the PATH setting in your shell configuration so it applies to future terminals. Then install again:

    npm install -g @openai/codex

  3. Reinstall a missing optional dependency

    Use the default reinstall command from the pinned launcher:

    npm install -g @openai/codex@latest

  4. Distinguish installation from network problems

    If Codex starts but you need a network check, codex doctor --network-only is available since v0.166.0, according to the release notes.

    codex doctor --network-only

FAQ

How do I install the Codex CLI?

Run npm install -g @openai/codex, or use brew install --cask codex.

Which Node.js version does the npm package require?

The pinned Codex CLI package declares Node.js >=16.

Should I use sudo to install Codex with npm?

Don't use sudo. Set the npm global prefix to a user directory, add its bin directory to PATH, then install Codex again.

How do I fix a missing optional dependency?

Reinstall Codex with npm install -g @openai/codex@latest, the default reinstall command in the pinned launcher source.

Sources

This is an independent, unofficial help site. It is not affiliated with or endorsed by OpenAI. Check the linked documentation and reports for your environment.