Installing the Codex CLI

Start with the mental model, because it makes every command below obvious: the Codex CLI is a single self-contained codex binary, written in Rust. It is not a thick Node application; npm is just one of several delivery trucks that drop the same compiled binary onto your machine. Whether you install via npm, Homebrew, a shell script, or by downloading a tarball, you end up with the identical codex executable on your PATH.

That matters for two reasons. First, you don't need a particular package manager — pick whichever fits your environment. Second, because it's a native binary, it runs locally: it reads, edits, and runs code on your machine inside an OS-enforced sandbox, not in a remote container (that's the cloud surface, a separate lesson).

Here are the four front doors, all installing the same binary:

The rest of this lesson walks each door, then covers the OS matrix, verifying, and updating.

These are the two most common paths, and each has exactly one gotcha that bites newcomers.

npm (cross-platform)

npm install -g @openai/codex

The trap: the package is the scoped @openai/codex. There is an unrelated, unofficial package published as the bare name codex on npm — installing that gives you the wrong tool entirely. Always include the @openai/ scope. The CLI requires Node ≥ 16, and it installs a codex command on your PATH.

Homebrew (macOS)

brew install --cask codex

The trap: Codex ships as a Homebrew cask, not a formula. The --cask flag is mandatory — brew install codex (no flag) resolves to a different, unrelated formula. Casks deliver the prebuilt binary directly, which is exactly what you want here.

Both managers make updating trivial later (npm update -g @openai/codex, brew upgrade --cask codex), though Codex also ships its own codex update command (covered at the end).

When you don't have Node or Homebrew — a fresh server, a CI runner, a colleague's laptop — the official install scripts are the fastest route.

macOS / Linux

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

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Unattended / CI

The interactive script may prompt. For pipelines and scripted provisioning, set CODEX_NON_INTERACTIVE=1 so it never asks:

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

By default the script installs into ~/.local/bin (on Windows, %LOCALAPPDATA%\Programs\OpenAI\Codex\bin). Override the destination with CODEX_INSTALL_DIR — handy when ~/.local/bin isn't on PATH, or when you want one shared location on a build agent.

Prebuilt binaries (GitHub Releases)

For air-gapped machines, pinned versions, or full control over PATH, grab the platform tarball straight from GitHub Releases and drop codex somewhere on your PATH. The target triples you'll see:

The Linux binaries are static musl builds, so they run on a wide range of distros without glibc-version headaches.

Codex runs natively on all three major desktop OSes. The detail that matters is which architectures and how the sandbox is enforced — because Codex refuses to run unsandboxed rather than act without an OS-enforced boundary, so the platform's sandbox support is part of "is this supported."

On macOS the sandbox is built into the OS, so installs "just work." On Linux, the most common first-run failure — "couldn't set up sandbox" — almost always means bubblewrap is missing or user namespaces are restricted; install/enable bubblewrap and it clears up. The Windows story has enough nuance that it gets its own section next.

Windows has two equally legitimate ways to run Codex, plus one version of WSL that no longer works. Get this right up front and you'll skip the most common Windows install headaches.

1. Native Windows (PowerShell sandbox). Codex runs directly on Windows using a PowerShell-based sandbox, configured in config.toml with two modes:

• elevated (preferred) — dedicated lower-privilege sandbox users, filesystem permission boundaries, and firewall rules. Best isolation and performance.
• unelevated (fallback) — a restricted token derived from your own user with ACL-based filesystem boundaries; weaker network isolation.

2. WSL2. Runs the full Linux sandbox (bubblewrap) inside Windows. Reach for it when you want a Linux-native environment — many toolchains assume Linux, and WSL2 gives you that without leaving Windows.

3. WSL1 — no longer supported. This is the gotcha. At CLI 0.115, the Linux sandbox moved to bubblewrap, which WSL1 cannot provide. WSL1 was supported only through 0.114 and dropped at 0.115. If you're on WSL1, upgrade your distro to WSL2 (wsl --set-version <distro> 2) before installing Codex.

Version guidance: Windows 11 is recommended; recent Windows 10 (1809+) is best-effort and depends on a modern console / ConPTY.

However you installed, confirm the binary is on PATH and runnable before you go further:

codex --version      # prints the installed version
codex --help         # lists subcommands and global flags

If codex isn't found, the install directory likely isn't on your PATH — the script default is ~/.local/bin; add it to PATH (or reinstall with CODEX_INSTALL_DIR pointed at a directory that already is).

For a deeper sanity check, Codex ships a built-in diagnostic:

codex doctor         # checks install, config, auth, runtime, Git, terminal

codex doctor generates a local report covering your install, config, auth state, and runtime; it's the first thing to run when something looks off (and --json produces a redacted report you can attach to a bug).

Updating

Codex updates itself with one command, regardless of how you installed it:

codex update

If you installed via a package manager you can also use that manager (npm update -g @openai/codex, brew upgrade --cask codex). The CLI moves fast — new versions land frequently — so don't memorize a version number. Check the live releases page for what's current and what changed.