Part of the AI Coding Harness Guide — environment design for coding agents in production.

How to Install Codex CLI on Windows, WSL, macOS and Linux#

Published by

Install Codex CLI with curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS, Linux and WSL, or powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" in Windows PowerShell. npm install -g @openai/codex and brew install --cask codex also work. Then run codex in a project folder and choose Sign in with ChatGPT.[1]

Codex CLI, the Codex app and ChatGPT desktop#

Codex is OpenAI's coding agent, and it runs in four places. Codex CLI is the terminal program this guide installs: a codex (on Windows codex.exe) command that reads, edits and runs code in your local repository. Codex in the ChatGPT desktop app for macOS and Windows is a separate install: open the app and choose Codex instead of ChatGPT in the composer. On Windows the desktop app comes from the Microsoft Store (winget install --id 9PLM9XGG6VKS -s msstore), and codex app opens it from a terminal, or starts its installer when it is missing. Codex Web at chatgpt.com/codex is the cloud agent, and the IDE extension runs in VS Code, Cursor and Windsurf. The CLI and the IDE extension share one cached login.[2][3][4]

Install commands for each system#

All commands below are from the Codex CLI docs and README for release 0.169.0 (2026-11-13). After an install, open a new terminal and run codex --version.

SystemInstallUpdate
macOS, Linux, WSL 2curl -fsSL https://chatgpt.com/codex/install.sh | shSame command, or codex update
Windows PowerShellpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Same command, or codex update
Any system with npmnpm install -g @openai/codexSame command, or codex update
macOS (Homebrew)brew install --cask codexbrew upgrade --cask codex
macOS, Linux (manual)Archive from the latest GitHub ReleaseDownload the new archive

The npm package is @openai/codex. npm install codex installs an unrelated package with that name. @openai/codex 0.169.0 declares node >=16 and pulls one of 6 prebuilt platform packages: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64 and win32-x64.[5]

Install Codex CLI on macOS and Linux#

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

The standalone installer puts codex in ~/.local/bin (change it with CODEX_INSTALL_DIR) and keeps release files under ~/.codex/packages/standalone. It supports x86_64 and arm64 and stops with Unsupported architecture on anything else. It downloads from releases.openai.com/codex and falls back to GitHub Releases when that download fails; set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false to use GitHub Releases only. Pin a version with --release 0.169.0 or CODEX_RELEASE=0.169.0.[1][6]

For a manual install, download the archive for your platform from the latest GitHub Release, unpack it, and rename the file inside to codex:

  • Apple Silicon: codex-aarch64-apple-darwin.tar.gz
  • Intel Mac: codex-x86_64-apple-darwin.tar.gz
  • Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
  • Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

Install Codex CLI on Windows with PowerShell#

Open a new PowerShell window and run:

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

The installer puts codex.exe in %LOCALAPPDATA%\Programs\OpenAI\Codex\bin and adds that folder to your User PATH, so open a new terminal before you run codex. npm install -g @openai/codex also works on Windows. The docs list no WinGet package for the CLI: the WinGet command above installs the ChatGPT desktop app, not codex.exe. Copying only codex.exe from a GitHub Release is not a complete install, because the standalone runtime files must stay together.[1][7]

Windows versionSupport
Windows 11Recommended
Windows 10 1809 or newer, fully updatedBest effort; needs ConPTY
Older Windows 10 buildsNot recommended

Windows sandbox status#

Native Windows Codex runs commands in a Windows sandbox that enforces the file and network limits of the active permission profile. There are 3 implementations:[8]

  • mxc: recommended. Uses Microsoft Execution Containers, with no administrator setup, extra Windows accounts or firewall rules. Needs Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278) with MXC rolled out. The desktop app picks it on its own for consumer accounts; the standalone CLI uses it when config.toml has prefer_mxc = true under [features].
  • elevated: the fallback when MXC is not available. One administrator-approved setup creates lower-privilege sandbox users and firewall rules; commands still run without administrator rights.
  • unelevated: the last fallback when admin setup is blocked. Weaker network isolation, and no denied read paths.

On Codex CLI 0.162.0 (2026-10-08) or later, test MXC for one command from a project folder. A working setup prints MXC_OK and exit code 0:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
$LASTEXITCODE

To pick a fallback, set it in config.toml:

[windows]
sandbox = "elevated" # or "unelevated"

Install Codex CLI in WSL#

Use WSL 2 when you need Linux tools, when your repositories already live in WSL, or when no native Windows sandbox works on your machine. In WSL, Codex uses the Linux sandbox instead of the Windows one. WSL 1 worked through Codex 0.114 (2026-03-11); from 0.115 (2026-03-16) the Linux sandbox uses bubblewrap, and WSL 1 is not supported.[9]

From an elevated PowerShell or Windows Terminal:

wsl --install
wsl

Then in the WSL shell:

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

Keep repositories under your Linux home folder, for example ~/code/my-app, not under /mnt/c/...: Windows-mounted paths are slower and cause more symlink and permission problems. Windows sees those files at \\wsl$\Ubuntu\home\<user>.

Sign in: ChatGPT account or API key#

Run codex and choose Sign in with ChatGPT, or run codex login. A browser opens, and Codex usage then counts against your ChatGPT plan: Plus, Pro, Business, Edu or Enterprise. Codex cloud needs a ChatGPT sign-in.[1][4]

With an API key, usage is billed at standard API rates to your OpenAI Platform account, and features that rely on ChatGPT workspace access or cloud services are limited or unavailable. Pipe the key on stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

On a remote or headless machine, run codex login --device-auth (beta; first allow device code login in your ChatGPT security settings), or forward the login callback with ssh -L 1455:localhost:1455 user@remote and run codex login there. codex login status exits with 0 when credentials are present, and codex logout removes them. Credentials are cached in ~/.codex/auth.json or the OS credential store, set by cli_auth_credentials_store; treat auth.json like a password.[4][10]

Update Codex CLI#

Run codex update. It finds how Codex was installed and runs the matching command:[11]

Installed withcodex update runs
npmnpm install -g @openai/codex
pnpmpnpm add -g @openai/codex
Bunbun install -g @openai/codex
Homebrewbrew upgrade --cask codex
Standalone, macOS or Linuxinstall.sh again, with CODEX_NON_INTERACTIVE=1
Standalone, Windows$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

If it cannot tell, it stops with Could not detect the Codex installation method. Please update manually; then run the install command for your system again.

Uninstall Codex CLI#

  • npm: npm uninstall -g @openai/codex
  • Homebrew: brew uninstall --cask codex
  • Standalone: there is no codex uninstall command. The installer writes ~/.local/bin/codex and ~/.codex/packages/standalone on macOS and Linux, and %LOCALAPPDATA%\Programs\OpenAI\Codex\bin plus a User PATH entry on Windows.[6][7]

~/.codex (or CODEX_HOME) also holds config.toml and auth.json; remove it only if you want those gone too. To remove the legacy elevated Windows sandbox accounts and firewall rules, stop the apps that use it and run codex sandbox uninstall as an administrator; it keeps your Codex home.[10]

Common install errors#

Error or symptomCauseFix
codex is not recognized after installThe terminal started before PATH changedOpen a new terminal; check the install folder is on PATH
An old version starts after an updateTwo installs (npm, Homebrew, standalone) on PATHGet-Command codex in PowerShell or which codex shows which one runs; the standalone installer offers to uninstall the npm or Homebrew copy
install.sh supports macOS and Linux. Use install.ps1 on Windows.install.sh ran in Git Bash or MSYS on WindowsUse the PowerShell command, or run install.sh inside WSL
Unsupported architectureCPU is not x86_64 or arm64No prebuilt Codex for that CPU
npm install codex installs the wrong toolcodex on npm is a different packagenpm install -g @openai/codex
Codex fails under WSL 1WSL 1 support ended at 0.114Move the distribution to WSL 2, or use native Windows
Windows error 1385 in sandboxed commandsWindows policy denies the logon right the elevated sandbox users needAsk IT to grant it, or use unelevated meanwhile
elevated sandbox setup failedUAC prompt declined, or policy blocks local users or firewall rulesRetry and approve the prompt; check MXC first

For anything else, codex doctor writes a diagnostic report on installation, configuration, authentication and runtime health, and Windows sandbox logs are in CODEX_HOME/.sandbox/sandbox.log.[8][10]

Standalone installer, npm or Homebrew?#

Use the standalone installer unless your machines get tools from a package manager. It needs no Node.js, verifies a SHA-256 digest of every download, and codex update re-runs it for you. Use npm when your team pins tools through an npm mirror, and pin a version with npm install -g "@openai/codex@0.169.0". Use Homebrew on a Mac that already manages tools with it. Keep one install method per machine: with two, PATH order decides which codex runs.


FAQ#

Q: What is the command to install Codex CLI?

A: curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS, Linux and WSL, powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" in Windows PowerShell, npm install -g @openai/codex anywhere with npm, or brew install --cask codex on macOS.

Q: Does Codex CLI run natively on Windows?

A: Yes. Install it from PowerShell. It runs commands in a native Windows sandbox: MXC on supported Windows 11 builds, otherwise the elevated or unelevated sandbox. Windows 11 is recommended; Windows 10 1809 or newer is best effort.

Q: Should I use WSL or native Windows for Codex?

A: Native Windows by default. Choose WSL 2 when you need Linux tools, your repositories already live in WSL, or no Windows sandbox works on your machine. WSL 1 is not supported since Codex 0.115.

Q: Is there a WinGet package for Codex CLI?

A: Not in the docs. winget install --id 9PLM9XGG6VKS -s msstore installs the ChatGPT desktop app, which includes Codex, but not the codex command line tool.

Q: What is the difference between Codex CLI and Codex in the ChatGPT app?

A: Codex CLI is the codex terminal program. The ChatGPT desktop app for macOS and Windows is a separate install with a Codex mode next to ChatGPT. Both can sign in with a ChatGPT account, and codex app opens the desktop app from a terminal.

Q: Can I use Codex CLI without a ChatGPT subscription?

A: Yes, with an OpenAI API key: printenv OPENAI_API_KEY | codex login --with-api-key. Usage is billed at API rates. With a ChatGPT sign-in, Codex comes with Plus, Pro, Business, Edu and Enterprise plans.

Q: How do I update Codex CLI?

A: Run codex update. It runs the update command for your install method, for example npm install -g @openai/codex or brew upgrade --cask codex.

Q: How do I uninstall Codex CLI?

A: npm uninstall -g @openai/codex or brew uninstall --cask codex. A standalone install has no uninstall command; its files are in ~/.local/bin/codex and ~/.codex/packages/standalone, or %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows.


Sources: [1] Codex CLI docs: Getting started and openai/codex README | [2] ChatGPT desktop app for Windows | [3] ChatGPT desktop app | [4] Codex docs: Authentication | [5] npm: @openai/codex | [6] install.sh | [7] Deploy the Windows app and Codex CLI | [8] Codex docs: Windows sandbox | [9] Codex docs: WSL | [10] Codex CLI command reference | [11] update_action.rs at rust-v0.169.0

Related: Codex CLI versions | Codex CLI config.toml reference | Codex CLI permissions reference | Codex "stream disconnected before completion" | How to install and update Claude Code

Get the weekly digest

New Claude Code, Codex, Gemini CLI and OpenCode guides and release analyses, once a week, plus occasional notes.

One email a week plus occasional notes. Confirm by email; unsubscribe from any issue. Privacy