#1 mistake: do not run npm i -g codex — that installs an unrelated 2012 project. The correct command is npm install -g @openai/codex. The @openai/ scope is required.
Prerequisite: Node.js 18 or later
The Codex CLI runs on Node.js and requires Node.js 18 or later (as of 2026). Check your current version first:
$ node -v
# should print v18.x.x or higher, e.g. v22.4.0If your version is too old or Node is not installed, the cleanest approach is nvm (Node Version Manager). It installs Node in your home directory, avoiding the global permission issues that plague system-level Node installs:
# install nvm
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# open a new terminal, then:
$ nvm install 22
$ nvm use 22
$ node -v # v22.x.xWindows users can download the LTS installer from nodejs.org, or use winget install OpenJS.NodeJS.LTS in an elevated PowerShell.
Method 1: npm global install (recommended)
Works on macOS, Linux, and Windows. One command:
$ npm install -g @openai/codexVerify the installation:
$ codex --version
# prints the version number if install succeededIf you see a version number (e.g. 0.1.x), the install was successful. Next step: run codex and sign in — see Verify & first run.
Method 2: official install script (macOS / Linux)
OpenAI ships a one-liner shell script for macOS and Linux. Re-running the same command also upgrades to the latest version:
$ curl -fsSL https://chatgpt.com/codex/install.sh | shThe script detects your platform and installs the right binary. To upgrade later, run the same command again — no extra flags needed.
Method 3: Homebrew (macOS)
If you already use Homebrew, install and upgrade Codex through it:
# install
$ brew install codex
# upgrade
$ brew upgrade codexInstalling on Windows
As of 2026 there are two ways to use Codex CLI on Windows:
Option A: PowerShell (native + Windows Sandbox)
Run npm install -g @openai/codex in PowerShell and use the CLI directly. Codex uses the Windows Sandbox for operations that require isolation.
Option B: WSL2 (Linux environment, fewest issues)
Inside a WSL2 Linux distro, install Node and Codex exactly as you would on Linux. This path tends to have the fewest compatibility issues, and is recommended if you already develop inside WSL2.
Running Codex inside WSL2 requires configuring a proxy separately — WSL2 does not automatically inherit the Windows system proxy. See the WSL2 section in the Reconnecting guide.
Verify & first run
After installing, verify and complete the first-time sign-in:
- Confirm the version:
$ codex --version - Launch Codex (first run prompts you to sign in):
$ codex # you will be prompted to sign in with ChatGPT or enter an API key - Choose your login method: ChatGPT account (requires a Plus, Pro, Business, Edu, or Enterprise subscription) or an OpenAI API key (billed per token). The CLI itself is free and open source.
Once signed in you will see ● connected. Try a quick test: type a simple instruction like list files in the current directory and confirm it responds.
Upgrade & uninstall
Upgrading
# npm
$ npm install -g @openai/codex@latest
# official script (re-running upgrades in place)
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Homebrew
$ brew upgrade codexUninstalling
# npm uninstall
$ npm uninstall -g @openai/codex
# optional: remove config and auth (clears login)
$ rm -rf ~/.codexCommon install errors
The CLI runs but behaves completely wrong
Cause: you installed the unscoped codex package (an unrelated 2012 project) instead of @openai/codex.
# remove the wrong package
$ npm uninstall -g codex
# install the correct one
$ npm install -g @openai/codexEngine version mismatch / syntax error on startup
Cause: Node.js version below 18. Confirm with node -v and upgrade via nvm:
$ nvm install 22 && nvm use 22
$ npm install -g @openai/codexnpm EACCES permission denied
Cause: npm's global directory is not writable by your user. Do not use sudo npm install — it creates permission tangles and is a security risk. The clean fix is to manage Node with nvm, which places the global prefix inside your home directory:
# install nvm if you haven't already
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# open a new terminal, then install Node
$ nvm install 22 && nvm use 22
# global npm installs now require no sudo
$ npm install -g @openai/codexnpm download is very slow or times out
Switch to a registry mirror closer to you:
# use npmmirror (fast in East Asia)
$ npm config set registry https://registry.npmmirror.com
$ npm install -g @openai/codex
# restore the official registry (optional)
$ npm config set registry https://registry.npmjs.orgThe registry mirror only speeds up the npm download. Running codex still requires a proxy to reach OpenAI on restricted networks. See Proxy & restricted networks and Fix Reconnecting.
FAQ
Which package name is correct — @openai/codex or codex?
It must be @openai/codex (with the @openai/ scope). Running npm i -g codex without the scope installs an unrelated 2012 package that has nothing to do with the Codex CLI. This is the #1 mistake newcomers make.
Does it need exactly Node 18, or will an older version work?
Node.js 18 or later is required (as of 2026). Run node -v to check. Node 16 and below will fail with compatibility errors. Managing Node with nvm is recommended so you can switch versions easily.
The install is very slow — how do I speed it up?
Switch to a nearby registry mirror: npm config set registry https://registry.npmmirror.com. After installing, restore the default with npm config set registry https://registry.npmjs.org. Note that running codex still requires a proxy to reach OpenAI — see the proxy guide.
Installed successfully but codex keeps showing Reconnecting?
That is a network issue, not an install issue. Codex needs to reach OpenAI, and on networks that block it the CLI loops on Reconnecting. Set HTTPS_PROXY to a local http proxy to fix it. See the full Reconnecting troubleshooting checklist.