If you've tried to install OpenAI's Codex CLI and ended up staring at an EEXIST error, a command not found, or a tool that just doesn't do anything resembling a coding agent, you're not alone. The single most damaging mistake is also the easiest to make: typing npm i -g codex instead of npm install -g @openai/codex. That one missing scope (@openai/) installs a completely different package — and Codex itself has historically suggested the wrong command.
This guide walks through every supported install method, OS by OS, and flags the traps before you fall into them.
The npm trap (read this first)
The official npm package is the scoped name @openai/codex. Install it like this:
npm install -g @openai/codex
Here's the trap. Running the unscoped version:
# DO NOT run this — wrong package
npm i -g codex
...installs an unrelated documentation generator published back in 2012. It targets Node.js 0.4.x–0.7.x, bundles long-deprecated dependencies like Jade and Connect 1.x, and has nothing to do with OpenAI. It will not function as a coding agent. Worse, if you install it on top of a working Codex install, npm can throw an EEXIST error.
The kicker: Codex CLI has at times printed the wrong upgrade command (
npm install -g codexrather than the scoped name), which is exactly how many users land in the wrong package. This is tracked in GitHub issue #9356. Always type the@openai/scope yourself.
If you've already made this mistake, clean up first:
npm uninstall -g codex
npm install -g @openai/codex
Choosing an install method
There are three real options. Pick based on how much you care about Node.js.
| Method | Node.js required? | Best for |
|---|---|---|
npm (@openai/codex) | Yes — Node 22+ | Devs already living in the Node ecosystem |
| Homebrew cask | No | macOS / Linux users who want managed updates |
| Standalone binary / install script | No | Anyone who wants zero Node dependency, CI, servers |
The npm path needs Node.js 22 or later. The binary and script paths are Rust builds with no Node.js requirement at all — which is why they're the cleanest option if you don't otherwise need Node.
macOS
Option 1 — Homebrew (recommended)
Use the cask, not a formula:
brew install --cask codex
The --cask flag installs a prebuilt application bundle instead of compiling from source. A plain brew install codex is not the documented path.
Option 2 — Install script (no Node)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
For unattended installs, set CODEX_NON_INTERACTIVE=1 first.
Option 3 — npm
npm install -g @openai/codex
Requires Node 22+.
Option 4 — Direct binary
Download from GitHub Releases. Match your chip:
- Apple Silicon (M-series):
codex-aarch64-apple-darwin.tar.gz - Intel:
codex-x86_64-apple-darwin.tar.gz
Extract, rename the executable to codex, and move it somewhere on your PATH (e.g. /usr/local/bin). Not sure which chip you have? uname -m returns arm64 for Apple Silicon and x86_64 for Intel.
Linux
Option 1 — Install script (recommended)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Option 2 — Direct binary
From GitHub Releases:
- x86_64:
codex-x86_64-unknown-linux-musl.tar.gz - arm64:
codex-aarch64-unknown-linux-musl.tar.gz
Extract, rename to codex, and place it on your PATH.
Option 3 — npm
npm install -g @openai/codex
Again, Node 22+.
Windows
Windows is where the npm path gets bumpy, so consider the alternatives first.
Native vs WSL2
OpenAI officially supports Windows natively. The native agent runs commands in PowerShell and uses a Windows-native sandbox. If you run Codex under WSL2 instead, it uses Linux sandboxing (Landlock/seccomp) — the same sandbox the models were primarily trained against, which makes WSL2 the stronger choice for Linux-first stacks and tighter isolation.
A caveat worth flagging: some 2026 sources still describe native Windows CLI support as experimental, while OpenAI's app documentation presents native as production-ready. The sources disagree, so test your own workflow before relying on it.
Option 1 — Microsoft Store / winget
winget install Codex -s msstore
Option 2 — Install script (PowerShell, no Node)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Set CODEX_NON_INTERACTIVE=1 for unattended installs.
Option 3 — npm (with the Windows fix)
A plain npm install -g @openai/codex on Windows can fail at runtime with:
Missing optional dependency @openai/codex-win32-x64. Reinstall Codex...
The platform-specific binary subpackage isn't always resolved on global installs. Don't try to install @openai/codex-win32-x64 directly — it's an alias target and returns a 404. Instead, use this community workaround (PowerShell) that pins the main package and the Windows binary to the same version:
$v = npm view @openai/codex version
npm install -g "@openai/codex@$v" "@openai/codex-win32-x64@npm:@openai/codex@$v-win32-x64"
After that, codex --version should work. This is a community workaround tracked in issues #12931 and #17432 and may change as packaging improves — if you'd rather not deal with it, the Store package or install script sidestep npm entirely.
First run
Once installed, just run:
codex
You'll be prompted to sign in with a ChatGPT account or an API key. (For the tradeoffs between those two, see the related post on ChatGPT login vs. API key.)
Updating and PATH gotchas
Updating
The built-in self-update is simplest:
codex update
Or update through your original channel:
npm update -g @openai/codex # npm
brew upgrade --cask codex # Homebrew
Keep one install channel per machine. Mixing npm, Homebrew, and the install script leaves multiple codex executables on disk, and the oldest one can win in your PATH.
"It still shows the old version"
Shells (bash/zsh) cache command locations. After updating, if codex --version reports the old number:
hash -r # bash
rehash # zsh
...or just open a new terminal. If it still shows the old version, you have multiple installs. Find them all:
which -a codex
"command not found" after npm install
This is almost always because your npm global bin directory isn't on PATH. Locate it:
npm prefix -g # binaries live in <prefix>/bin
Add that bin directory to your shell PATH, reload, and you're set.
Bottom line
Codex CLI is easy to install once you avoid the one fatal typo. Type the scoped package name — @openai/codex — every single time, and never trust an upgrade prompt that drops the @openai/ scope. If you don't need Node.js for other work, skip npm entirely: the Homebrew cask (brew install --cask codex), the install script, or the standalone Rust binary all give you a clean, Node-free install. On Windows, prefer the Store package or install script over npm to dodge the missing-subpackage bug, and choose WSL2 when you want the Linux sandbox. Stick to a single install channel, remember that your shell caches binary paths, and codex --version will tell you the truth after a fresh terminal.