How to Install OpenAI Codex CLI on Mac and Windows

OpenAI Codex CLI is a lightweight coding agent that runs directly in your terminal. It can read and write files, execute commands, and help you build software using natural language prompts.

Prerequisites

Before installing Codex CLI, ensure you have:

• Node.js 18 or higher (for npm installation method)
• A ChatGPT subscription (Plus, Pro, Team, Edu, or Enterprise) OR an OpenAI API key with available credits
• Git (recommended for version control before making changes)

To check your Node.js version:

node --version

If you need to install Node.js, download it from nodejs.org or use a version manager like nvm.

Installing on macOS

macOS users have three installation options.

Option 1: Homebrew (Recommended)

Homebrew is the easiest method for macOS users:

brew install codex

To update Codex later:

brew upgrade codex

Option 2: npm

If you prefer npm or do not have Homebrew installed:

npm install -g @openai/codex

Option 3: Direct Binary Download

Download the appropriate binary from the GitHub Releases page:

• Apple Silicon (M1/M2/M3/M4): codex-aarch64-apple-darwin.tar.gz
• Intel Macs: codex-x86_64-apple-darwin.tar.gz

After downloading:

# Extract the archive
tar -xzf codex-aarch64-apple-darwin.tar.gz

# Move to a directory in your PATH
mv codex /usr/local/bin/

# Verify installation
codex --version

Installing on Windows

Windows support is available through npm or WSL.

Option 1: npm on Windows

Open PowerShell or Command Prompt:

npm install -g @openai/codex

Option 2: WSL (Recommended)

For the most reliable Windows experience, use Codex within WSL:

1. Install WSL if you have not already:

wsl --install

2. Open your WSL terminal (Ubuntu or your preferred distribution)

3. Install Node.js in WSL:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

4. Install Codex CLI:

npm install -g @openai/codex

Windows Notes

• Codex defaults to GPT-5 on Windows (versus GPT-5-Codex on macOS/Linux)
• For the best experience with file system operations, WSL is recommended

Authentication

After installation, run Codex for the first time:

codex

Option 1: Sign in with ChatGPT (Recommended)

Select Sign in with ChatGPT when prompted. This links Codex to your existing ChatGPT subscription.

Benefits:

• Uses your existing subscription quota
• No separate API billing
• Access to the latest models included in your plan

Option 2: API Key Authentication

If you prefer to use an API key:

1. Get your API key from platform.openai.com/api-keys
2. Set the environment variable:

macOS/Linux:

export OPENAI_API_KEY="your-api-key-here"

Windows (PowerShell):

$env:OPENAI_API_KEY="your-api-key-here"

To make this permanent, add the export command to your shell profile (~/.zshrc, ~/.bashrc, or Windows environment variables).

Verify Installation

After authentication, verify everything is working:

codex --version

Then try a simple task:

codex "create a hello world python script"

Basic Usage

Once installed, you can use Codex for various coding tasks:

# Generate code
codex "write a function to validate email addresses in Python"

# Review code
codex review

# Work on specific files
codex -f myfile.py "add error handling to this script"

Troubleshooting

"command not found: codex"

If you installed via npm but the command is not found:

1. Check your npm global bin directory:

npm bin -g

2. Ensure that directory is in your PATH

3. Try reinstalling:

npm uninstall -g @openai/codex
npm install -g @openai/codex

Authentication Issues

If you have trouble signing in:

1. Clear any existing credentials:

codex auth logout

2. Try signing in again:

codex

WSL File Permission Issues

If Codex cannot write files in WSL:

sudo chown -R $USER:$USER .

Next Steps

• Explore the official Codex documentation
• Learn about Codex CLI features
• Install Google Gemini CLI for free access to a 1M token context window
• Learn how to orchestrate multiple AI tools using Claude as an Engineering Manager