How to Install OpenAI Codex CLI on Ubuntu

Codex CLI is OpenAI’s lightweight coding agent that runs directly in your terminal. It reads your codebase, executes shell commands, edits files, runs tests, debugs issues — all through natural language. Think of it as ChatGPT natively integrated into your terminal workflow.

This guide covers every installation method on Ubuntu, from beginner-friendly to advanced.

1. Prerequisites

Before you start, make sure your system meets these requirements:

2. Installation Methods

Method 1: Official Install Script (Recommended)

OpenAI provides an official one-liner. It detects your OS and architecture, downloads the correct binary, and places it in your PATH.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

After the script finishes, you’re ready to go:

codex

Tip: Want to inspect the script before running? Pipe it to less:
curl -fsSL https://chatgpt.com/codex/install.sh | less

Method 2: npm

If you already have Node.js set up, npm is the most portable option:

# Install Node.js 18+ first if needed
# curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# sudo apt install -y nodejs

# Install Codex CLI globally
npm install -g @openai/codex

# Verify installation
codex --version

To upgrade later:

npm install -g @openai/codex@latest

⚠️ Avoid npm update -g — it respects the semver range from the original install and may not pull the latest release.

Method 3: Binary Download (No Node.js Required)

For a self-contained binary without any runtime dependencies, download directly from GitHub Releases:

x86_64 systems:

wget https://github.com/openai/codex/releases/latest/download/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

ARM64 systems:

wget https://github.com/openai/codex/releases/latest/download/codex-aarch64-unknown-linux-musl.tar.gz
tar -xzf codex-aarch64-unknown-linux-musl.tar.gz
sudo mv codex-aarch64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

Method 4: Homebrew

If you use Homebrew on Linux:

brew install --cask codex

3. Authentication

On first run, Codex CLI needs to authenticate. You have two options:

ChatGPT Login (Recommended for Subscribers)

codex login

This opens a browser window where you sign in with your OpenAI account. Usage is then tied to your ChatGPT plan — Plus, Pro, Team, Edu, or Enterprise. No API key needed.

API Key

If you prefer using an API key:

export OPENAI_API_KEY="sk-proj-..."

# Persist it in your shell config
echo 'export OPENAI_API_KEY="sk-proj-..."' >> ~/.bashrc
source ~/.bashrc

Then launch:

codex

4. First Run

Navigate to your project directory and start:

cd ~/my-project
codex

Codex CLI will scan your codebase and present an interactive prompt. Try commands like:

Configuration

Preferences are stored in ~/.codex/config.toml. You can customize the default model, approval mode, and MCP servers there.

5. Upgrade

6. Uninstall

Also remove config if desired:

rm -rf ~/.codex

7. Troubleshooting

“codex: command not found”

• Curl / Binary install: Check if /usr/local/bin is in your PATH: echo $PATH. If not, add export PATH="/usr/local/bin:$PATH" to ~/.bashrc.
• npm: Verify the package is installed: npm list -g --depth=0 | grep codex.
• Try opening a new terminal or running hash -r to refresh the command cache.

Authentication fails

• Confirm your OpenAI account has an active subscription (Plus, Pro, Team, Edu, Enterprise), or your API key is valid and has credits.
• Try codex logout then codex login to re-authenticate.

Permission errors on Linux

If you see EACCES errors when installing globally with npm:

# Option 1: Use a Node version manager (nvm) — recommended
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
npm install -g @openai/codex

# Option 2: Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

Codex starts but can’t read files

Codex needs filesystem access. Make sure you’re in a directory you own and have read/write permissions. On remote servers, ensure the filesystem is not mounted as read-only.

Summary

For most Ubuntu users, the official curl installer is the simplest path — one command, no dependency chain, and it handles architecture detection automatically.

Codex CLI is open source (GitHub, Apache-2.0) and under active development with over 94,000 stars. Whether you’re debugging a legacy codebase, generating boilerplate, or exploring a new repository, it’s a powerful addition to your terminal toolkit.