Install Codex CLI: the documented ways

Codex install methods at a glance

Not listed in the CLI docs: a winget, scoop, apt or snap install for the CLI itself. The docs do mention winget, but as a prerequisite on Windows and for the desktop app, not as a way to install the CLI.

How to download Codex: installer, package manager or release archive

The one-line installers fetch the binary for you. If you would rather download it by hand, the repository README points to the latest GitHub Release and names these archives: codex-aarch64-apple-darwin.tar.gz (Apple Silicon), codex-x86_64-apple-darwin.tar.gz (older Mac hardware), codex-x86_64-unknown-linux-musl.tar.gz and codex-aarch64-unknown-linux-musl.tar.gz (Linux). After extracting, the single file inside carries the platform in its name, so the README says to rename it to codex.

The same README says the standalone installers download from releases.openai.com/codex by default and fall back to GitHub Releases; setting CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false forces GitHub Releases.

The IDE extension is a separate download: the “Install the extension” link in the IDE docs points to the Visual Studio Marketplace item openai.chatgpt. Per the open-source page, the IDE extension is not open source.

Codex CLI for Mac: installer, Homebrew or release archive

On macOS the documented routes are the standalone installer, npm, or Homebrew (below). The only Mac-specific statements this guide found are the archive names above (Apple Silicon versus older Intel hardware) and a minimum macOS release in the repository's docs/install.md, which also lists Git as optional but recommended and a memory recommendation; the docs site itself states no macOS minimum.

brew install codex: the Homebrew cask

The documented command is brew install --cask codex. Note the --cask: it is a cask, and the docs show no plain formula-style install. Update it later with brew upgrade --cask codex.

Codex install npm: the @openai/codex package

The npm package is @openai/codex and the documented command is npm install -g @openai/codex. No docs page states a Node.js requirement for the CLI at all; the only machine-readable statement is the engines field in the repository's package manifest, which declares a minimum Node.js release. The standalone installer does not need Node.js.

Codex install Linux: the standalone installer

Linux uses the same standalone installer as macOS (curl -fsSL https://chatgpt.com/codex/install.sh | sh); the script itself says it supports macOS and Linux and points Windows users to install.ps1. By default it puts codex in ~/.local/bin and adds that directory to PATH through a shell profile, then prints how to run codex in the current terminal versus a new one. CODEX_INSTALL_DIR changes where the command goes.

Linux sandbox prerequisites (Ubuntu and others)

On Linux the sandbox uses bwrap (bubblewrap): Codex uses the first bwrap on PATH and otherwise falls back to a bundled helper that needs unprivileged user namespaces. The sandboxing docs have Ubuntu-release-specific notes: on one release, installing bubblewrap from Ubuntu's repository should work without extra AppArmor setup; on another, Codex may still warn that it cannot create the needed user namespace, and the docs give an AppArmor profile fix. The minimum Ubuntu and Debian releases appear only in the repository's docs/install.md, not on the docs site.

Codex on Windows and WSL: the official sources disagree

This is one of the places where the official sources contradict each other, so here are both sides:

• Repository docs/install.md lists “Windows 11 via WSL2” as the Windows option in its requirements table (file; last changed in June 2026).
• The docs site documents a native Windows installer (the PowerShell command above), a native Windows sandbox, and a Windows version matrix in which Windows 11 is “Recommended” and a recent, fully updated Windows 10 is “Best effort” (Windows sandbox page). The README also gives the PowerShell command.

The docs do not label the native Windows CLI “experimental” or “supported”; they give the installer and the version matrix and nothing more on that point.

Codex WSL: the documented WSL2 setup

With WSL2, Codex runs inside the Linux environment instead of the native Windows sandbox. The WSL page says to choose WSL2 when you need Linux-native tooling or your repositories already live in WSL2. Its steps: from an elevated PowerShell or Windows Terminal run wsl --install and then wsl, install Codex inside WSL with the Linux installer, and keep repositories under your Linux home directory (like ~/code/my-app) rather than /mnt/c/.... To confirm the binary is on PATH inside WSL the page suggests which codex || echo "codex not found". WSL1 is no longer supported. The IDE extension has a Windows-only setting, chatgpt.runCodexInWindowsSubsystemForLinux, to run Codex in WSL. If you have several WSL distributions installed, OpenAI’s Help Center (Using Codex with your ChatGPT plan) says you can choose which Linux distribution Codex uses, and to run codex doctor in the Codex CLI for diagnostics covering startup, connectivity and performance issues.

How to set up Codex after installing: first run and sign-in

1. Open a project directory and run codex. The first time, choose Sign in with ChatGPT or another available sign-in method (CLI docs).
2. To sign in from the command line: codex login, then complete the browser flow. For an API key: printenv OPENAI_API_KEY | codex login --with-api-key. On a headless machine the docs describe device-code login (beta) with codex login --device-auth.
3. Check which method is active with codex login status; codex logout clears stored credentials.

The auth docs say the CLI, IDE extension and desktop app support both ChatGPT and API-key sign-in for local work, while Codex cloud requires ChatGPT sign-in. Login details are cached in ~/.codex/auth.json or your operating system's credential store, and the browser callback defaults to localhost:1455. For settings after install, see the config.toml guide; for what you can use before hitting a limit, see checking your usage.

Verify the Codex CLI installation

Print the installed version with codex --version (the troubleshooting page gives that command). The desktop app bundles its own Codex, which can be a different version from the CLI. If the installation looks broken, codex doctor produces a local diagnostic report covering installation, configuration, authentication, runtime, Git and terminal health (command reference).

How to update Codex CLI

Codex CLI update commands by install method

For unattended standalone updates the environment-variable docs show curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh. The startup update check is controlled by check_for_update_on_startup in config.toml.

A small discrepancy, labelled as source code and not documentation: comments in the open-source CLI's update_action.rs mention npm install -g @openai/codex@latest and brew upgrade codex, but the arguments that file actually runs are the ones in the table. Not found in the sources checked: how to pin or roll back to a specific CLI version, and how the IDE extension is updated. There is no documented codex upgrade subcommand; the documented one is codex update.

Not found in the sources checked

• A Node.js requirement for the CLI on any docs page checked (only the repository manifest declares one).
• macOS, Linux or Ubuntu minimum versions on the docs site checked (only the repository's docs/install.md has them).
• A label calling the native Windows CLI “experimental” or “supported”.
• Pinning or rolling back a CLI version; updating the IDE extension. OpenAI’s Help Center may cover these; this guide read only its article on using Codex with your plan.
• Content from openai.com/codex, which could not be retrieved when this guide was checked.