How to Install Codex CLI on macOS and Linux in 2025

OpenAI's Codex CLI is a lightweight coding agent that runs directly in your terminal, making it easy to get AI-assisted coding without leaving your command line. If you're a developer looking to integrate Codex into your workflow on macOS or Linux, this guide covers three installation methods and troubleshooting tips.

Why Use Codex CLI?

Codex CLI offers several advantages over the web-based version:

• Local execution: Runs entirely on your machine without uploading code to the cloud
• Terminal-native: Integrates seamlessly with existing shell workflows
• ChatGPT plan integration: Works with your existing ChatGPT Plus, Pro, Business, Edu, or Enterprise subscription
• No extra setup: Single command to get started

Installation Method 1: npm (Fastest for Node.js Users)

If you already have Node.js and npm installed, this is the quickest way to get Codex running:

npm install -g @openai/codex

This installs Codex globally, making it available from any terminal window. After installation completes, verify it worked:

codex --version

You should see the version number printed to your terminal. If you get a command not found error, your npm global bin directory may not be in your PATH. Add it by running:

export PATH="$(npm config get prefix)/bin:$PATH"

Add this line to your shell profile (.bashrc, .zshrc, or .config/fish/config.fish) to make it permanent.

Installation Method 2: Homebrew (Recommended for macOS)

MacOS users with Homebrew installed can use the cask:

brew install --cask codex

Homebrew handles PATH setup automatically, so Codex should be immediately available in your terminal. Verify:

codex --version

To update Codex when new versions release:

brew upgrade codex

Installation Method 3: Binary Download (Linux and macOS Manual Setup)

For Linux users or macOS users preferring manual control, download precompiled binaries from the GitHub Releases page.

macOS Binary Installation

Choose the correct binary for your architecture:

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

Download and extract:

# Example for Apple Silicon
wget https://github.com/openai/codex/releases/download/v[VERSION]/codex-aarch64-apple-darwin.tar.gz
tar -xzf codex-aarch64-apple-darwin.tar.gz
mv codex-aarch64-apple-darwin ~/bin/codex
chmod +x ~/bin/codex

Ensure ~/bin is in your PATH:

export PATH="$HOME/bin:$PATH"

Linux Binary Installation

Select the appropriate Linux binary:

• x86_64 (standard servers): codex-x86_64-unknown-linux-musl.tar.gz
• ARM64 (Raspberry Pi, mobile Linux): codex-aarch64-unknown-linux-musl.tar.gz

Download and install:

# Example for x86_64
wget https://github.com/openai/codex/releases/download/v[VERSION]/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

Configuration: Sign in with ChatGPT

After installation, start Codex:

codex

You'll be prompted to authenticate. OpenAI recommends signing in with your ChatGPT account:

Would you like to sign in with ChatGPT? [Y/n]

Press Y and follow the browser-based authentication flow. This gives you access to your existing ChatGPT plan (Plus, Pro, Business, Edu, or Enterprise) without additional costs.

Alternative: API Key Authentication

If you prefer to use an OpenAI API key instead:

1. Generate an API key at platform.openai.com/api/keys
2. Run codex and select the API key option
3. Paste your key when prompted

Note: API key usage may have separate billing from ChatGPT plans.

Installation Comparison Table

| Method | Platform | Ease | Updates | Best For | |--------|----------|------|---------|----------| | npm | macOS, Linux, Windows | High | Automatic with npm update -g @openai/codex | Node.js developers | | Homebrew | macOS | High | brew upgrade codex | macOS-primary users | | Binary | macOS, Linux | Medium | Manual download | Custom PATH control |

Troubleshooting

"codex: command not found"

• Ensure npm global bin is in PATH, or reinstall with Homebrew
• Check echo $PATH to verify /usr/local/bin or npm's global directory is listed

"Authentication failed"

• Clear cached credentials: Remove ~/.codex directory
• Re-run codex and authenticate again

Version mismatch on Linux

• Verify your CPU architecture: uname -m
• Download the matching binary (x86_64 vs aarch64)

Next Steps

Once Codex is running, you can:

• Use it directly in your terminal for code generation and debugging
• Install the Codex extension in VS Code, Cursor, or Windsurf for IDE integration
• Try the desktop app with codex app for a graphical interface
• Visit Codex documentation for advanced usage

Codex CLI integrates seamlessly into developer workflows on both macOS and Linux, whether you prefer terminal-first development or IDE integration.