How to Install Codex CLI on Ubuntu (26.04, 24.04, 22.04)

This guide explains how to install Codex CLI on Ubuntu using npm, Homebrew, or standalone binaries. Codex CLI is an agentic coding tool from OpenAI that operates directly in your terminal, understanding your codebase context, executing shell commands, and helping you write code through natural language conversations. Unlike web-based AI assistants, Codex CLI runs locally with full access to your project files, git history, and development environment. The tool uses models like o4-mini by default, with options to select other OpenAI models depending on your subscription.

Common use cases include exploring unfamiliar codebases, implementing features from natural language descriptions, debugging errors with stack traces, running automated code reviews on uncommitted changes, and managing multi-turn coding sessions. By the end of this guide, you will have Codex CLI installed on Ubuntu, authenticated with your OpenAI account, and ready to start interactive coding sessions within any git repository.

Choose Your Codex CLI Installation Method

You can install Codex CLI on Ubuntu through three different methods, each suited to different system configurations. If you already have Node.js 18 or higher installed, the npm method provides the quickest path. Users who manage tools through Homebrew can use the familiar cask installation workflow. For systems without Node.js or Homebrew, the binary method downloads standalone executables that work immediately after extraction.

Method	Channel	Version	Updates	Best For
npm	npm Registry	Latest	Manual via npm update	Node.js developers, most users
Homebrew	Homebrew Cask	Latest	Manual via brew upgrade	Users who manage tools through Homebrew
Binary	GitHub Releases	Latest	Manual download	Users without Node.js, minimal installs

The npm method suits most users because it provides straightforward installation and updates through familiar package management. If you already have Node.js installed for development, this is the fastest path to getting started.

These steps cover Ubuntu 26.04 LTS, 24.04 LTS, and 22.04 LTS. Codex CLI requires a ChatGPT Plus, Pro, Team, Edu, or Enterprise subscription, or an OpenAI API key with active billing. Commands shown work identically across all supported Ubuntu LTS releases.

System Requirements

Before installing Codex CLI, verify your system meets these requirements:

• Operating System: Ubuntu 26.04, 24.04, or 22.04 LTS
• Node.js: Version 18 or higher (for npm installation method only)
• RAM: 4 GB minimum
• Internet: Active connection required for authentication and AI interactions
• Subscription: ChatGPT Plus, Pro, Team, Edu, Enterprise, or OpenAI API key with billing

The binary installation method does not require Node.js, making it suitable for minimal server environments or systems where you prefer not to install Node.js.

Method 1: Install Codex CLI via npm

OpenAI recommends the npm method as the primary installation approach because it integrates with the Node.js ecosystem most developers already use. This method requires Node.js 18 or higher.

Install Node.js

If Node.js is not already installed, add the NodeSource repository and install it:

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

The curl command uses -fsSL flags to follow redirects silently and output only the script content, which pipes to bash for execution.

Verify Node.js installed correctly:

node --version

v22.22.0

Install Codex CLI Globally

Install Codex CLI as a global npm package:

npm install -g @openai/codex

Do NOT use sudo npm install -g as this creates permission issues and security risks. If you encounter permission errors, configure npm to use a directory in your home folder for global packages, or use a Node version manager like nvm.

Verify Installation

Confirm the installation completed successfully:

codex --version

codex-cli 0.87.0

Method 2: Install Codex CLI via Homebrew

If you already use Homebrew to manage development tools on your system, the Homebrew cask offers a familiar installation workflow. This method works independently of Node.js, so you can install Codex CLI even if Node.js is not present on your system.

Install Homebrew (If Not Present)

If Homebrew is not installed on your system, add it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installer displays commands to add Homebrew to your PATH at the end of installation. Without these commands, your shell cannot find the brew command. For most users on Ubuntu, the setup looks like this:

echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
source ~/.bashrc

The source command applies the changes immediately without opening a new terminal. The PATH modification persists automatically for future sessions.

Install Codex CLI

Install Codex CLI using the Homebrew cask:

brew install --cask codex

The Homebrew cask automatically installs ripgrep as a dependency, which Codex uses for fast code searching. You do not need to install ripgrep separately.

Verify Installation

Confirm the installation completed successfully:

codex --version

codex-cli 0.87.0

Method 3: Install Codex CLI via Binary Download

The binary method downloads pre-built executables directly from GitHub releases. This approach works without Node.js or Homebrew, making it ideal for minimal server environments or systems where you prefer manual control over updates.

Download the Binary

Download the latest Linux binary for your architecture. For x86_64 systems (most desktop and server installations):

curl -fsSL https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz -o codex.tar.gz

For ARM64 systems (like Raspberry Pi or ARM-based cloud instances), use codex-aarch64-unknown-linux-musl.tar.gz instead. Check your architecture with uname -m.

Extract and Install

Extract the archive and move the binary to a location in your PATH:

tar -xzf codex.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

The tar -xzf command extracts the gzipped tarball. The chmod command with +x marks the file as executable so your shell can run it.

Clean up the downloaded archive:

rm codex.tar.gz

Verify Installation

Confirm the binary is accessible and working:

codex --version

codex-cli 0.87.0

Authenticate Codex CLI

Codex CLI requires authentication before you can interact with the AI. OpenAI offers two authentication methods: ChatGPT account login (recommended) and API key authentication.

Authentication Options

Codex CLI supports the following authentication methods:

• ChatGPT subscription (recommended): Sign in with your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan
• OpenAI API key: Use an API key from the OpenAI Platform with active billing for pay-per-use access

First Launch Authentication

Navigate to your project directory and start Codex CLI:

cd ~/your-project
codex

On first launch, Codex CLI prompts you to select an authentication method. Choose “Sign in with ChatGPT” for subscription-based access. This opens a browser window for OAuth authentication where you:

1. Sign in with your ChatGPT account
2. Authorize Codex CLI to access your account
3. Return to the terminal where authentication completes automatically

After successful authentication, Codex CLI displays an interactive terminal interface where you can start entering prompts. Codex stores your credentials in ~/.codex/ along with session history and configuration files.

Manage Authentication

Switch accounts or re-authenticate using these commands:

codex login     # Sign in or switch to a different account
codex logout    # Sign out from your current account

Common Commands and Usage

Codex CLI responds to natural language prompts and provides several subcommands for different workflows.

Interactive Mode

Start an interactive session where you can have a conversation with the AI:

codex

You can also provide an initial prompt:

codex "explain the authentication flow in this project"

Non-Interactive Execution

Run commands non-interactively for scripting or quick tasks:

codex exec "add a new endpoint to handle user registration"

Code Review

Run an automated code review on your changes. You must specify what to review using one of these flags:

# Review uncommitted changes (staged and unstaged)
codex review --uncommitted

# Review changes compared to a specific branch
codex review --base main

# Review a specific commit
codex review --commit HEAD~1

# Provide custom review instructions
codex review "focus on security vulnerabilities"

Session Management

Resume or fork previous conversations:

codex resume          # Pick from previous sessions
codex resume --last   # Continue the most recent session
codex fork --last     # Fork the most recent session into a new one

Apply Changes

Apply a diff produced by Codex to your local working tree. This requires the task ID from a previous Codex session:

codex apply <task-id>

Task IDs appear in the Codex output when it generates changes. Use codex resume to list previous sessions and their task IDs.

Sandbox Modes

Control how Codex executes commands with sandbox policies. These determine what level of autonomy Codex has when interacting with your filesystem and running commands:

• read-only: Codex can read files but cannot write or execute commands. Safest option for exploring code.
• workspace-write: Codex can read and write files within your project directory but cannot execute shell commands without approval.
• danger-full-access: Codex has full read/write access and can execute commands. Use only when you trust the operations being performed.

codex --sandbox read-only
codex --sandbox workspace-write
codex --sandbox danger-full-access

The --full-auto flag enables automatic execution with sandboxing constraints. On Linux, this uses Docker containerization with network restrictions to limit potential damage:

codex --full-auto

Working with Images

Attach images (screenshots, diagrams) to your prompts:

codex -i screenshot.png "implement this UI design"

Model Selection

Specify which model to use:

codex --model o3 "optimize this function"

Update Codex CLI

Update procedures differ by installation method. Use the same approach you used for installation.

Update npm Installation

Update to the latest version using npm:

npm update -g @openai/codex

Or install the latest version explicitly:

npm install -g @openai/codex@latest

Update Homebrew Installation

Update Codex CLI through Homebrew:

brew upgrade codex

Update Binary Installation

Binary installations update by replacing the existing file with the new release. Download the latest version for your architecture and overwrite the current installation:

x86_64 systems:

curl -fsSL https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz -o codex.tar.gz
tar -xzf codex.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
rm codex.tar.gz

ARM64 systems:

curl -fsSL https://github.com/openai/codex/releases/latest/download/codex-aarch64-unknown-linux-musl.tar.gz -o codex.tar.gz
tar -xzf codex.tar.gz
sudo mv codex-aarch64-unknown-linux-musl /usr/local/bin/codex
rm codex.tar.gz

Troubleshooting

Command Not Found After Installation

If codex returns “command not found” after npm installation, the npm global bin directory may not be in your PATH.

Find the npm global bin directory:

npm config get prefix

Add the bin directory to your PATH:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

The source ~/.bashrc command applies the PATH change immediately. Alternatively, open a new terminal window for the changes to take effect.

Verify the command is now accessible:

codex --version

Node.js Version Error

If you see errors about Node.js version compatibility, verify your Node.js version:

node --version

Codex CLI requires Node.js 18 or higher. If your version is older, upgrade Node.js using the NodeSource repository or a version manager like nvm.

Authentication Errors

If authentication fails or becomes stuck, reset the authentication state:

codex logout
codex login

If problems persist, remove stored credentials and re-authenticate:

rm -rf ~/.codex
codex

Authentication in Headless or SSH Environments

Browser-based OAuth authentication does not work in headless servers or SSH sessions without display forwarding. For these environments, use API key authentication instead of the ChatGPT login flow.

Set your OpenAI API key as an environment variable:

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

To make this persistent across sessions, add it to your shell configuration:

echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

The source ~/.bashrc command loads the environment variable immediately without requiring a new terminal session.

Codex CLI detects the environment variable and uses API key authentication automatically. Get an API key from the OpenAI Platform with active billing enabled.

Permission Denied Errors with npm

If npm installation fails with EACCES permission errors, do not use sudo npm install. Instead, configure npm to use a directory in your home folder:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

The source ~/.bashrc command applies the new PATH configuration immediately. Retry the installation:

npm install -g @openai/codex

Binary Download Issues

If the binary download fails or the extracted file does not run, verify your system architecture:

uname -m

x86_64

If output shows aarch64, download the ARM64 binary instead of the x86_64 version.

Remove Codex CLI

Remove Codex CLI using the same method you used for installation.

Remove npm Installation

npm uninstall -g @openai/codex

Remove Homebrew Installation

brew uninstall --cask codex

Remove Binary Installation

sudo rm /usr/local/bin/codex

Remove Configuration Files (Optional)

Codex CLI stores configuration and session data in ~/.codex/. This directory contains authentication tokens, session history, and any custom configuration. Remove these files only if you want to completely reset your configuration or are uninstalling permanently:

This permanently deletes all Codex CLI configuration, session history, and authentication credentials. You will need to re-authenticate after reinstalling.

rm -rf ~/.codex

Common Questions

Conclusion

Codex CLI is now installed and configured on Ubuntu, enabling AI-assisted development directly from your terminal. The npm method provides the simplest installation for Node.js users, while Homebrew and binary options offer alternatives for different environments and preferences.

To get started with your first project, navigate to your codebase directory and run codex. Use codex --help for a complete list of options and subcommands. For ongoing usage, codex resume lets you continue previous conversations, and codex review --uncommitted provides automated code review of your staged and unstaged changes.