2026-07-14

How to Install OpenAI Codex CLI on Mac, Windows & Linux (2026)

Q: Do I need a ChatGPT subscription to install Codex CLI?

You can install without one. Running Codex for serious use generally needs a ChatGPT plan that includes Codex, or an API key path. Free/limited tiers may allow tryouts with tight caps — check OpenAI’s current Codex pricing notes.

Q: Can I install Codex CLI without npm?

Yes. Prefer the native installer (curl on macOS/Linux, PowerShell on Windows) or brew install --cask codex. GitHub release binaries work offline after download. npm is optional.

Q: How do I update Codex CLI?

Prefer codex update (built into the CLI from 0.144.3). If that is missing or fails, fall back to re-running the official install script (native), brew upgrade --cask codex, or npm install -g @openai/codex@latest. Then codex --version.

Install OpenAI Codex CLI on macOS, Windows, and Linux with native installer, Homebrew, or npm. Fix command not found, PATH, and update Codex — full troubleshooting.

This guide covers every common install path for the OpenAI Codex CLI in 2026 — Mac, Windows, Linux — plus the error that fills search and social: command not found: codex. Commands match the official Codex CLI docs and openai/codex README; when in doubt, prefer those pages. Local reference version while writing: codex-cli 0.144.3 (releases move fast).

Before you install

You need:

A supported OS: modern macOS, Windows 10+ (native or WSL), or a current Linux distro (x64 or arm64)
Internet access to download the installer / package
A way to authenticate: ChatGPT sign-in (Plus, Pro, Business, Edu, Enterprise — plan-dependent Codex access) or an API key path for local tasks

Node is not required for the native installer (curl / PowerShell / Homebrew cask). The official @openai/codex package currently declares Node 16+; we recommend Node 18+ for the npm install path.

Two install families:

Native / standalone installer (recommended) — no Node required; re-run the same script to update
Package managers — Homebrew cask, or a global npm install if you already live in Node

Install on macOS

Option A — native installer (recommended):

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

Same command updates Codex later (official docs: re-run the installer).

Option B — Homebrew:

brew install --cask codex

If a cask install goes stale after an upgrade and you see command not found: codex, community reports often fix it with a clean reinstall:

brew uninstall --cask codex
brew install --cask codex

Then open a new terminal.

Option C — npm:

npm install -g @openai/codex

Requires a working Node toolchain. If the binary never appears on PATH, use the command not found section below — July 2026 threads still show codex: command not found after a clean npm install -g when the global bin dir is missing from PATH (nvm/fnm scoping is a common cause).

Then:

codex

Install on Windows

Pick native Windows or WSL based on where your projects live.

Native Windows

PowerShell (look for PS C:\...):

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

(Shorter form once execution policy allows: irm https://chatgpt.com/codex/install.ps1 | iex.)

npm (if you already use Node on Windows):

npm install -g @openai/codex

After install, if codex is not recognized, check for a shim or binary under your user profile — PATH is often the issue. npm global installs typically create a codex.cmd shim (not codex.exe); the native PowerShell installer may land a codex.exe. See the Windows PATH steps below. Community reports also note tools that shell out to a bare codex command fail when only a full path works.

WSL

Open your WSL distro and use the Linux installer (do not install from PowerShell into WSL):

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

Use WSL2 when you need a Linux toolchain for the agent.

Install on Linux

Native installer (most distros):

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

npm:

npm install -g @openai/codex

Binary from GitHub Releases (air-gapped or package-manager-free machines): download the archive for your arch from github.com/openai/codex/releases, extract, rename the platform-tagged binary to codex, and put it on PATH. Examples:

Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

There is no official apt / dnf / apk package today — use the installer script, npm, or a GitHub release binary.

Desktop / app surfaces: OpenAI also ships Codex via ChatGPT desktop and codex app flows; this page is the CLI path. For Linux desktop packaging questions, start from the official Codex CLI and open source docs.

Verify and update

codex --version

First run of codex in a project directory walks you through Sign in with ChatGPT (or API-key setup).

Update (preferred): from 0.144.3 onward Codex ships an official in-CLI updater:

codex update

Fallback by install method if codex update is unavailable or fails:

Native installer (macOS/Linux): re-run curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows native: re-run the PowerShell installer
Homebrew: brew upgrade --cask codex (or uninstall/reinstall if the cask is wedged)
npm: npm install -g @openai/codex@latest

If an upgrade leaves you with command not found even though it worked yesterday, treat it as a PATH / shim problem first (community “codex cli broken after upgrade” reports), not a missing ChatGPT subscription.

Fix: codex command not found

This is the exact string people paste: command not found: codex (or bash codex: command not found, Windows “not recognized”). Install often succeeded; PATH did not. Variants in the wild include “managed standalone Codex install not found at PATH” after a broken upgrade — re-run the official curl | sh installer, then fix PATH if needed.

1. Confirm whether any binary exists

command -v codex
ls -la ~/.local/bin/codex 2>/dev/null
which -a codex 2>/dev/null

Empty command -v with a file under ~/.local/bin → PATH issue. No file at all → reinstall with the matching method for your OS.

2. Check PATH (macOS/Linux)

Native installs commonly land under ~/.local/bin. Check:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

No output → add it. zsh (default on macOS):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

New terminal, then:

codex --version

3. npm global bin not on PATH

npm install -g @openai/codex succeeds, then command not found:

command -v codex          # empty if not on PATH
npm prefix -g             # e.g. /usr/local — binary lives in <prefix>/bin
npm root -g               # package install location
# add <prefix>/bin to PATH the same way as above

Do not use npm’s old global-bin listing command (removed in npm 11+). Prefer npm prefix -g and npm root -g only. Temporary workaround:

npx @openai/codex

If you use nvm/fnm, install global packages in the same shell version you use day-to-day, or every new Node version looks like a “missing codex” regression.

4. Windows PATH after install

Installer finished, but codex is not found. Check all three common shapes:

Get-Command codex -ErrorAction SilentlyContinue
Get-Command codex.cmd -ErrorAction SilentlyContinue
Get-Command codex.exe -ErrorAction SilentlyContinue
$env:PATH -split ';' | Select-String 'codex|\.local\\bin|npm'

npm globals usually expose codex.cmd (a shim under the npm global prefix bin)
Native PowerShell installer may install codex.exe under a user-local bin dir

Append the directory that contains the shim or binary to User PATH, restart the terminal, re-check codex --version. To add %USERPROFILE%\.local\bin (the native installer’s default) to User PATH permanently from PowerShell:

$currentpath = [environment]::GetEnvironmentVariable('path', 'user')
[environment]::SetEnvironmentVariable('path', "$currentpath;$env:USERPROFILE\.local\bin", 'user')

Close and reopen the terminal, then codex --version. Substitute npm prefix -g + \bin for the npm shim path instead of .local\bin if that is where your install landed.

5. Homebrew cask after upgrade

brew uninstall --cask codex
brew install --cask codex

Open a new terminal. If command -v codex is still empty, check where the cask linked the binary (brew info --cask codex) and ensure that directory is on PATH.

6. Conflicting installs

which -a codex

You can have a native binary, a Homebrew shim, and an npm -g install at once. Prefer one path; remove or deprioritize the others if versions fight.

After installing: run it from anywhere

cd /path/to/your/project
codex

From there: sign in, describe a task, review diffs. For plan and credit economics, see Codex pricing (2026); if you are choosing an agent, compare Codex CLI vs Claude Code. For a model-specific mobile workflow, see GPT-5.6 Codex from your phone. For a live session dashboard while Codex runs on your machine, Codex usage with SeaWork and remote control keep the agent local and put the control UI on your phone or desktop.

FAQ

Do I need a ChatGPT subscription to install Codex CLI? You can install without one. Running Codex for serious use generally needs a ChatGPT plan that includes Codex, or an API key path. Free/limited tiers may allow tryouts with tight caps — check OpenAI’s current Codex pricing notes.

Can I install Codex CLI without npm? Yes. Prefer the native installer (curl on macOS/Linux, PowerShell on Windows) or brew install --cask codex. GitHub release binaries work offline after download. npm is optional.

How do I update Codex CLI? Prefer codex update (built into the CLI from 0.144.3). If that is missing or fails, fall back to re-running the official install script (native), brew upgrade --cask codex, or npm install -g @openai/codex@latest. Then codex --version.

Sources

As of July 2026: