How to Install Codex CLI on Windows, WSL, macOS and Linux#
Published by Alex Sorokoletov
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.
| System | Install | Update |
|---|---|---|
| macOS, Linux, WSL 2 | curl -fsSL https://chatgpt.com/codex/install.sh | sh | Same command, or codex update |
| Windows PowerShell | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" | Same command, or codex update |
| Any system with npm | npm install -g @openai/codex | Same command, or codex update |
| macOS (Homebrew) | brew install --cask codex | brew upgrade --cask codex |
| macOS, Linux (manual) | Archive from the latest GitHub Release | Download 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 version | Support |
|---|---|
| Windows 11 | Recommended |
| Windows 10 1809 or newer, fully updated | Best effort; needs ConPTY |
| Older Windows 10 builds | Not 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 whenconfig.tomlhasprefer_mxc = trueunder[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 with | codex update runs |
|---|---|
| npm | npm install -g @openai/codex |
| pnpm | pnpm add -g @openai/codex |
| Bun | bun install -g @openai/codex |
| Homebrew | brew upgrade --cask codex |
| Standalone, macOS or Linux | install.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 uninstallcommand. The installer writes~/.local/bin/codexand~/.codex/packages/standaloneon macOS and Linux, and%LOCALAPPDATA%\Programs\OpenAI\Codex\binplus 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 symptom | Cause | Fix |
|---|---|---|
codex is not recognized after install | The terminal started before PATH changed | Open a new terminal; check the install folder is on PATH |
| An old version starts after an update | Two installs (npm, Homebrew, standalone) on PATH | Get-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 Windows | Use the PowerShell command, or run install.sh inside WSL |
Unsupported architecture | CPU is not x86_64 or arm64 | No prebuilt Codex for that CPU |
npm install codex installs the wrong tool | codex on npm is a different package | npm install -g @openai/codex |
| Codex fails under WSL 1 | WSL 1 support ended at 0.114 | Move the distribution to WSL 2, or use native Windows |
Windows error 1385 in sandboxed commands | Windows policy denies the logon right the elevated sandbox users need | Ask IT to grant it, or use unelevated meanwhile |
elevated sandbox setup failed | UAC prompt declined, or policy blocks local users or firewall rules | Retry 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