Getting Codex CLI to install cleanly on the first try would be nice. In reality, something almost always goes wrong. Wrong Node.js version, npm permission errors, API key not recognized — the usual developer gauntlet. This guide collects every common Codex CLI install issue in one place. Work through it top to bottom, and you'll resolve most problems before they snowball.

Prerequisites — Check These First

Before you even run the install command, verify three things.

Node.js 22 or higher: Codex CLI requires Node.js 22+. Versions 18 and 20 might let you install, but you'll hit runtime errors immediately.

[code lang="bash"] node -v

Must show v22.x.x or higher

[/code]

npm (up to date): The npm bundled with Node.js 22 works fine. Problems arise when an older global npm installation conflicts with the newer one.

OpenAI API key: Grab one from OpenAI Platform. You can't do anything without it.

Node.js Version Mismatch

This is the single most common reason a Codex CLI install fails.

Symptom: After running npm install -g @openai/codex, you see engine warnings. Or the install succeeds but running codex throws SyntaxError: Unexpected token.

Cause: Your system has Node.js 18 or 20. Codex CLI uses modern ECMAScript features that don't exist in older runtimes.

Fix:

[code lang="bash"]

nvm users

nvm install 22 nvm use 22

Homebrew users (macOS)

brew install node@22 [/code]

Multiple Node Versions Coexisting

If you use nvm, your default Node version can silently switch between terminal sessions. Installing Codex CLI under Node 22 but running it under Node 20 produces MODULE_NOT_FOUND errors.

[code lang="bash"] nvm alias default 22

Locks Node 22 as the default across all sessions

[/code]

Confirming the Active Node Path

Sometimes the node command points to a system-installed version even when nvm has a newer one. Run which node to confirm the active binary path. If it points to /usr/local/bin/node instead of an nvm-managed path like ~/.nvm/versions/node/v22.x.x/bin/node, your terminal isn't picking up the nvm version. Add nvm use default to your shell profile to fix this.

npm Permission Error — EACCES

Symptom: npm install -g @openai/codex fails with EACCES: permission denied.

Cause: The global npm directory is owned by root. This happens if you've ever run sudo npm install — even once.

Fix (Option 1 — Change npm's directory):

[code lang="bash"] mkdir /.npm-global npm config set prefix '/.npm-global'

Add to .bashrc or .zshrc

export PATH=~/.npm-global/bin:$PATH [/code]

Fix (Option 2 — Use nvm): Installing Node through nvm stores global packages in your user directory, eliminating permission issues entirely.

Avoid sudo npm install -g. It creates a chain of permission problems for every future update and uninstall.

API Key Configuration

The first run after a successful Codex CLI install is where most people get stuck.

Environment variable (recommended):

[code lang="bash"]

Add to .bashrc or .zshrc

export OPENAI_API_KEY="sk-..." [/code]

.env file: Create a .env file in your project root with OPENAI_API_KEY=sk-.... Codex CLI reads it automatically.

Method	Pros	Cons
Environment variable	Works in every directory	Requires terminal restart
.env file	Per-project isolation	Must keep out of git

Watch out: If you've set the key but still get Authentication error, check for trailing whitespace or mismatched quotes. Run echo $OPENAI_API_KEY to see the actual stored value.

Codex CLI Version Conflicts

Symptom: codex runs, but certain features (like GPT-5.5 model selection) are missing or throw errors.

Cause: Codex CLI ships frequent updates. If you installed at version 0.114 and never updated, features added in 0.123+ won't exist for you.

Fix:

[code lang="bash"] npm update -g @openai/codex codex --version

Verify you're on the latest

[/code]

Using GPT-5.5 requires the latest Codex CLI version. Older versions simply don't list it as an available model.

PowerShell Compatibility (Windows)

Windows users frequently hit a wall right after a Codex CLI install completes successfully.

Symptom: Typing codex in PowerShell returns "running scripts is disabled on this system."

Cause: PowerShell's Execution Policy defaults to Restricted, which blocks scripts installed via npm.

Fix:

[code lang="powershell"] Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned [/code]

Alternatively, use Git Bash or WSL. Codex CLI runs more reliably on Unix-style shells. If you're doing any serious development on Windows, WSL is worth the setup investment anyway.

Korean Encoding Setup

Once your Codex CLI install is complete, Korean developers should also check encoding settings. As covered in a previous post about Codex Korean text issues, the cloud sandbox's locale settings can break Korean filenames.

For your local environment, verify the terminal locale:

[code lang="bash"] locale

LANG=ko_KR.UTF-8 or en_US.UTF-8 means you're fine

[/code]

Codex CLI Install Checklist

Here's the complete process as a scannable checklist.

• Confirm Node.js 22+ is installed (node -v)
• Verify npm global permissions (npm list -g --depth=0)
• Run npm install -g @openai/codex
• Set OPENAI_API_KEY environment variable
• Confirm installation with codex --version
• On Windows: change PowerShell execution policy
• For Korean projects: verify locale settings

A clean Codex CLI install takes five minutes when nothing goes wrong. When something does go wrong — and it usually does — this checklist covers the fixes. Once you're set up, the only ongoing maintenance is running npm update -g @openai/codex periodically. If issues persist, the OpenAI Community forums are worth searching for your specific error message. Also check out the AI instructions series for setting up your development workflow after installation.