All tutorials / Codex/3 min/Beginner

Codex tutorial

How to Install OpenAI Codex CLI on Mac and Windows (via NPM)

Learn how to instantly install the newest OpenAI Codex CLI agent on Mac or Windows using npm. Includes exact commands and solutions to the common unexpected argument '-q' error.

4 stepsCopyable commandsCodex CLI
Interactive tutorial

Quick command sequence

$ npm install -g @openai/codex

/en/tutorials/install-openai-codex-cli-mac-windows-npm

Interactive command lab

1/4

Step 1

Check Node.js

Codex runs via Node.js. If you don't see version numbers, download Node.js first.

Checkpoint

node -v

zsh — tutorial-lab

Command tray

$ node -v && npm -v

➜ v20.10.0

➜ 10.2.3

Step-by-step instructions

  1. 1

    Step

    Check Node.js

    Codex runs via Node.js. If you don't see version numbers, download Node.js first.

    node -v && npm -v
  2. 2

    Step

    Install Codex Globally

    Using the `-g` flag ensures `codex` is added to your system PATH globally.

    npm install -g @openai/codex
  3. 3

    Step

    Verify Installation

    If you get 'command not found', you may need to restart your terminal or add NPM to your PATH.

    codex --version
  4. 4

    Step

    Avoid Old Flags

    Many older tutorials suggest using `codex -q`. This flag was removed and will crash modern versions.

    codex

Why this matters

Using the official `@openai/codex` NPM package ensures you have the latest features and security patches. Outdated tutorials often point to legacy Github repositories or recommend flags like `-q` that completely break the modern CLI on launch.

Troubleshooting

  • **Unexpected argument '-q'**: The `codex -q` flag was removed. Run the agent using just `codex`.
  • **EACCES permission denied**: If you get a permissions error on Mac, use a Node version manager like `nvm` or run `sudo npm install -g @openai/codex` (though `nvm` is heavily preferred).
  • **Command not found**: On Windows, ensure your NPM global installation path (`%USERPROFILE%\AppData\Roaming\npm`) is added to your Environment Variables PATH.

FAQ

What is the npm command for OpenAI Codex?

The official command is `npm install -g @openai/codex`. The `-g` flag is important because it makes the `codex` command available globally across all your project folders.

Does Codex CLI require Python or Node.js?

Codex CLI runs on Node.js. You do not need Python to install or run the standard Codex package, but you must have a recent version of Node.js installed.

Can I install Codex CLI with Homebrew instead of NPM?

While `brew install --cask codex` has been used historically for unofficial wrappers, the direct supported method from OpenAI is using NPM via the `@openai/codex` package.

How do I fix unexpected argument '-q' in Codex CLI?

Stop using the `-q` flag. Older versions used it to suppress prompts, but the current v0.130.0+ architecture rejects it. Just type `codex` and hit enter.

Is Codex CLI the same as Claude Code?

No. Codex is OpenAI's coding agent CLI, whereas Claude Code is Anthropic's terminal agent. They are installed differently and use different AI models on the backend.

Related tutorials

Copilot

How to Install GitHub Copilot CLI on Mac and Windows

Step-by-step guide to installing the GitHub Copilot CLI extension. Learn how to authenticate and run gh copilot suggest and explain in your terminal.

Aider

How to Install Aider AI Coding CLI on Mac and Windows

Step-by-step guide to installing the Aider AI pair programming CLI on macOS and Windows. Learn how to configure API keys for Claude 3.7 and GPT-4o.