Installation

Install Codex CLI on macOS, Linux, or Windows (via WSL2)

Installation

Codex CLI can be installed using npm, Homebrew, or by downloading pre-built binaries for your platform.

System requirements

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

Requirement	Details
Operating systems	macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2
Node.js	16 or newer (Node 20 LTS recommended for npm installation)
Git (recommended)	2.23+ for built-in PR helpers
RAM	4 GB minimum (8 GB recommended)

Codex CLI does not work directly on Windows. You must use Windows Subsystem for Linux (WSL2). See the WSL installation guide.

Installation methods

npm

1. Install globally with npm

   Install Codex CLI globally using your preferred package manager:

   npm

   npm install -g @openai/codex
   

   Never run sudo npm install -g. If you encounter permissions errors, fix your npm permissions instead.

2. Verify installation

   Verify that Codex is installed correctly:

   codex --version
   

   You should see the version number printed to your terminal.

Homebrew

1. Install with Homebrew

   Install Codex CLI using Homebrew (macOS and Linux):

   brew install --cask codex
   
2. Verify installation

   Verify that Codex is installed correctly:

   codex --version
   

   You should see the version number printed to your terminal.

Binary download

1. Download the binary

   Go to the latest GitHub Release and download the appropriate binary for your platform:

   macOS

   • Apple Silicon/arm64: codex-aarch64-apple-darwin.tar.gz
   • x86_64 (older Mac hardware): codex-x86_64-apple-darwin.tar.gz

   Linux

   • x86_64: codex-x86_64-unknown-linux-musl.tar.gz
   • arm64: codex-aarch64-unknown-linux-musl.tar.gz
2. Extract and rename

   Extract the archive and rename the binary:

   # Example for Linux x86_64
   tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
   mv codex-x86_64-unknown-linux-musl codex
   

   Each archive contains a single entry with the platform name baked in, so you’ll want to rename it to codex.

3. Make executable and move to PATH

   Make the binary executable and move it to a directory in your PATH:

   chmod +x codex
   sudo mv codex /usr/local/bin/
   
4. Verify installation

   Verify that Codex is installed correctly:

   codex --version
   

   You should see the version number printed to your terminal.

Build from source

1. Clone the repository

   Clone the Codex repository and navigate to the CLI package:

   git clone https://github.com/openai/codex.git
   cd codex/codex-cli
   
2. Enable corepack and install dependencies

   Enable corepack and install dependencies:

   corepack enable
   pnpm install
   
3. Build the CLI

   Build the CLI:

   pnpm build
   

   Linux only: Download prebuilt sandboxing binaries:

   ./scripts/install_native_deps.sh
   

   This requires gh (GitHub CLI) and zstd.

4. Link globally (optional)

   Link the command globally for convenience:

   pnpm link
   

   Or run directly:

   node ./dist/cli.js
   

Verify your installation

After installation, verify that Codex is working by running:

codex --help

You should see the help output with available commands and options.

Next steps

1. Authenticate

   Now that Codex is installed, set up authentication to start using the CLI.

2. Complete the quickstart

   Follow the quickstart guide to run your first commands.