How to Install the OpenAI Codex CLI: 4 Methods from npm to Source

You can install the OpenAI Codex CLI via npm for legacy TypeScript support, Homebrew for native macOS binaries, direct GitHub downloads for Linux/Windows, or by building the Rust source code directly.

The OpenAI Codex CLI is a command-line interface for the openai/codex repository that enables AI-powered coding assistance directly in your terminal. Whether you need the legacy TypeScript implementation or the modern Rust-based binary with full sandboxing capabilities, this guide covers every installation method with specific commands and source file references.

Installation Methods Overview

The Codex CLI offers four distinct installation paths, each suited to different operating systems and workflow preferences:

• npm (legacy TypeScript CLI) – Cross-platform Node.js package with a JavaScript shim wrapping the Rust binary
• Homebrew cask (macOS) – Pre-built native binary managed through Homebrew
• Direct download – Platform-specific binaries from GitHub Releases for Linux and Windows
• Build from source – Compile the Rust implementation locally for development or custom builds

Method 1: Install via npm (Legacy TypeScript CLI)

The npm distribution packages the CLI as @openai/codex and works on any platform running Node.js 16 or higher.

Installation Steps

Install the package globally to access the codex command from anywhere:

npm i -g @openai/codex

Verify the installation succeeded:

codex --version

Architecture Notes

According to the openai/codex source code, the npm package contains a thin JavaScript shim located in the legacy codex-cli/ directory. This shim launches the compiled Rust binary that ships as a bundled asset within the npm package. The actual CLI implementation resides in codex-rs/cli/src/main.rs, which handles subcommand dispatching.

Method 2: Install via Homebrew on macOS

For macOS users seeking a zero-dependency installation, Homebrew provides the Rust-based native binary through its cask system.

Installation Steps

Install the pre-built binary using Homebrew's cask command:

brew install --cask codex

Confirm the binary is available:

codex --version

Why Use Homebrew?

The Homebrew distribution delivers the Rust-based implementation described in codex-rs/README.md, which is the canonical and most feature-complete version of the CLI. This method avoids requiring Node.js or Rust toolchains on your system, as the cask downloads a pre-compiled binary that includes all subcommands (exec, tui, and cli).

Method 3: Direct Download from GitHub Releases

Linux and Windows users, or those who prefer manual installation, can download platform-specific binaries directly from the repository's releases page.

Linux and Windows Installation

1. Navigate to the GitHub Releases page: https://github.com/openai/codex/releases
2. Download the asset matching your platform (e.g., codex-linux-x86_64.tar.gz or codex-windows-x86_64.zip)
3. Extract the archive and move the binary to a directory in your $PATH

For Linux systems:

tar -xzf codex-linux-x86_64.tar.gz -C ~/.local/bin
chmod +x ~/.local/bin/codex
codex --version

This method provides the same Rust-based binary found in the Homebrew distribution, including the sandboxing capabilities documented in codex-rs/linux-sandbox/README.md.

Method 4: Build from Source (Rust)

Developers who need the latest unreleased changes or want to contribute to the project can compile the CLI from the Rust source code.

Prerequisites

Install the required Rust toolchain and task runner:

cargo install just
cargo install --locked cargo-nextest  # Optional, for testing

Building the Binary

Clone the repository and build the project:

git clone https://github.com/openai/codex.git
cd codex
just build

The just build command compiles the codex binary using the configuration defined in codex-rs/cli/Cargo.toml. The resulting binary appears in target/release/codex.

Install the binary to your local bin directory:

cp target/release/codex ~/.local/bin/
codex --version

Source Code Structure

The Rust implementation in codex-rs/ represents the canonical CLI architecture:

• codex-rs/cli/src/main.rs – Entry point that parses arguments and dispatches to subcommands
• codex-rs/cli/Cargo.toml – Defines the binary target and dependencies
• codex-rs/core/src/config_loader – Handles configuration file loading from ~/.codex/ directories
• codex-rs/linux-sandbox/ – Implements the sandboxing policies accessible via the --sandbox flag

Verifying Your Installation

Regardless of installation method, confirm the CLI functions correctly by checking its version and running a test command:

codex --version
codex chat "Write a Python function that returns fibonacci numbers"

The binary should respond with version information and process the natural language request using the OpenAI API.

Summary

• npm provides the quickest cross-platform installation using @openai/codex, wrapping the Rust binary in a Node.js shim.
• Homebrew delivers a native macOS binary without external dependencies via brew install --cask codex.
• Direct download from GitHub Releases suits Linux and Windows users who want pre-built binaries without package managers.
• Building from source requires the Rust toolchain and the just task runner, compiling the canonical implementation found in codex-rs/cli/src/main.rs.

All methods ultimately install the same multitool binary supporting exec, tui, and cli subcommands with full sandboxing capabilities.

Frequently Asked Questions

What is the difference between the npm and Homebrew installations?

The npm package (@openai/codex) installs a legacy TypeScript wrapper that launches the Rust binary, requiring Node.js 16 or higher. The Homebrew cask installs the native Rust binary directly to your macOS system without Node.js dependencies. Both provide the same codex command, but Homebrew offers better performance and the canonical implementation as described in codex-rs/README.md.

Do I need Node.js installed to use the Codex CLI?

You only need Node.js if you install via npm. The Homebrew, direct download, and source build methods provide native binaries that do not require Node.js or any JavaScript runtime. The Rust-based implementation in codex-rs/cli/ compiles to a standalone executable.

How do I update the Codex CLI to the latest version?

Update methods depend on your installation path. For npm, run npm update -g @openai/codex. For Homebrew, use brew upgrade --cask codex. If you built from source, pull the latest changes with git pull and rerun just build in the repository root, then copy the new binary from target/release/codex.

Where are configuration files stored after installation?

The CLI loads configuration from multiple sources as implemented in codex-rs/core/src/config_loader. It reads environment variables, .env files in the working directory, and user-specific settings stored in the ~/.codex/ directory. The binary also respects CLI flags like --sandbox which override config file settings without modifying global configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}