Install Codex CLI (macOS, Windows, Linux): One Command

Install OpenAI Codex CLI on macOS, Windows, or Linux with one command (install.sh, PowerShell, npm, or Homebrew), verify with codex --version, and sign in.

UniRoute · October 18, 2026

Copy and run the command for your operating system to install OpenAI's Codex CLI (@openai/codex), then verify with codex --version:

OS / Method	Recommended Install Command	Verify
macOS (Apple Silicon & Intel)	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh` (or `brew install --cask codex`)	`codex --version`
Linux (`x86_64` & `arm64`)	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	`codex --version`
Windows (PowerShell or WSL2)	`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` (or use the Linux command inside WSL2)	`codex --version`
npm alternative (Node.js >= 16)	`npm install -g @openai/codex`	`codex --version && codex doctor`

System requirements (verified 2026-10-18 from docs/install.md and @openai/codex@0.163.0 npm metadata; install.sh verified 2026-10-27 on Codex CLI docs): macOS 12+, Ubuntu 20.04+ / Debian 10+, or Windows 11 (native PowerShell or WSL2); 4 GB RAM minimum (8 GB recommended); Git 2.23+ optional; Node.js >= 16 is only required if you install via npm.

Next Step: First Run & Sign-In

Once codex --version prints your installed version, start Codex in your project folder:

Sign in with a ChatGPT account: Run codex and choose Sign in with ChatGPT (included with ChatGPT Plus, Pro, Business, Edu, or Enterprise plans; if you hit a plan window, see Codex Usage Limits).
Use an API Key (no ChatGPT plan required, or when your plan limit is used up): Local Codex CLI sessions also work with a direct OpenAI Platform API key or a UniRoute API key (create an API key). As of 2026-10-27, on UniRoute's discounted channel GPT models are as low as ~28% of official API rates (e.g., GPT 6 Sol is $0.56 / $2.80 per 1M input/output tokens vs. $2 / $10 official, and GPT 5.6 Terra is $0.56 / $3.36 vs. $2 / $12); when the discounted channel is unavailable, requests fail over automatically to the standard channel at official-level prices (how channels work; see UniRoute Pricing). Configure Codex CLI in one command:

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID

For full details, see the Codex CLI setup documentation or our Connect Codex to UniRoute tutorial (manual config.toml settings are also shown in Section 4 below).

1. Common Install and Startup Troubleshooting

If codex does not start immediately after installation, match your error below:

Symptom / message	Cause	Fix
`command not found: codex` right after running `install.sh`	Your current terminal session has not reloaded the shell profile updated by the installer (`~/.zprofile` or `~/.bash_profile` on macOS, `~/.zshrc` or `~/.bashrc` on Linux, or `~/.profile`, as printed in `"PATH was added to <profile>"`).	Open a new terminal window, or run the command printed by the installer: `export PATH="$HOME/.local/bin:$PATH" && codex`.
`Multiple managed Codex installs can be ambiguous because PATH order decides which one runs` (or an older version runs after install)	Both Homebrew (`/opt/homebrew/bin/codex`), npm, or `~/.local/bin/codex` exist on the same machine, and the older one appears earlier in `PATH`.	Run `which -a codex` (macOS/Linux) or `where.exe codex` (Windows) and uninstall the duplicate (`brew uninstall --cask codex` or `npm uninstall -g @openai/codex`).
Permission error (`EACCES`) on `npm install -g @openai/codex`	Your global npm prefix points to a system directory that your user account cannot write to.	Avoid `sudo npm install -g`. Use the official standalone installer (`install.sh`, which writes to `~/.local/bin`), a Node version manager, or a user-writable npm prefix.
`codex --version` still shows the old version after updating	Either you updated one package manager while another `codex` binary is first on `PATH`, or your shell cached the old binary lookup.	Check `which -a codex`, remove any second installation, and run `hash -r` in `bash`/`zsh` (or open a new terminal).
`codex doctor` prints `websocket ⚠ Responses WebSocket failed; HTTPS fallback may still work`	WebSocket probing to the Responses endpoint did not succeed, though standard HTTPS requests may still work.	Test an actual prompt first; if HTTPS requests also fail, inspect your proxy, VPN, firewall, DNS, or custom CA settings as suggested by `codex doctor`.
Windows PowerShell blocks script execution	PowerShell execution policy restricts running remote scripts in the current session.	Run the exact command from OpenAI's README, which passes `-ExecutionPolicy ByPass` for that process: `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"`.
Need verbose logs for a TUI bug	Default TUI logs are stored in bounded local stores.	Because Codex is written in Rust, it honors `RUST_LOG`. Run `codex -c log_dir=./.codex-log` and monitor `tail -F ./.codex-log/codex-tui.log` (`codex exec` prints `RUST_LOG=error` messages inline).

2. Choose an Installation Method (Comparison)

OpenAI ships Codex CLI through four prebuilt distribution channels plus source builds. Installing from more than one channel on the same machine is a common cause of stale versions because PATH order decides which codex binary runs.

Install method	Command / source	Where it installs	Pros & trade-offs
1. Official standalone installer	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh` (macOS/Linux, verified 2026-10-27) or `install.ps1` (Windows, verified 2026-10-18)	Binary link in `${CODEX_INSTALL_DIR:-~/.local/bin}/codex`; release files under `${CODEX_HOME:-~/.codex}/packages/standalone`; edits shell profile `PATH` when needed	No Node.js or Homebrew required. Detects existing `npm`/`brew`/`bun` installs and warns about `PATH` conflicts. Modifies your shell profile (`~/.zprofile` for `zsh` or `~/.bash_profile` for `bash` on macOS, `~/.zshrc` or `~/.bashrc` on Linux, and `~/.profile` for other shells) and prints which file it updated if `~/.local/bin` is not yet on `PATH`.
2. npm global install	`npm install -g @openai/codex`	Your active Node/npm global `bin` directory	Familiar for JavaScript/TypeScript teams and easy to pin an exact version (`@openai/codex@0.163.0`). Requires Node.js (`engines.node >= 16`).
3. Homebrew cask	`brew install --cask codex`	`$HOMEBREW_PREFIX/bin/codex` (e.g., `/opt/homebrew/bin/codex` on Apple Silicon) + bash/zsh/fish shell completions	No Node.js required; upgrades alongside `brew upgrade --cask codex`. Note: use `--cask`—there is no Homebrew formula named `codex`.
4. GitHub Release binary	Download from `github.com/openai/codex/releases/latest`	Anywhere you place the extracted binary (e.g., `~/.local/bin/codex`)	No installer script or package manager needed; ideal for locked-down or manual setups. You must extract and rename the platform binary to `codex` yourself; you must also update it manually when new releases ship.
5. Build from source	`cargo build` inside `codex-rs` (`docs/install.md`)	`codex-rs/target/debug/codex`	Only needed if you are developing or patching Codex CLI in Rust.

Windows Note: Native PowerShell Installer vs. Windows 11 via WSL2

As of 2026-10-18, OpenAI's two official documents in the openai/codex repository describe Windows support differently:

The main repository README lists a native Windows PowerShell installer (powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"), and the @openai/codex@0.163.0 npm package ships @openai/codex-win32-x64 and @openai/codex-win32-arm64 optional platform packages.
Meanwhile, docs/install.md in the same repository still lists Windows 11 via WSL2 in its system requirements table.

If you are on Windows, you can try the native PowerShell or npm route first, and switch to an Ubuntu 20.04+ or Debian 10+ environment inside WSL2 if a command or shell integration fails natively. (Note on WinGet: third-party package directories list a WinGet entry for Codex, but WinGet is not documented in OpenAI's official README or docs/install.md.)

3. Step-by-Step Installation Details by OS

macOS (Apple Silicon `arm64` and Intel `x86_64`)

Option A — Official standalone script (no Node or Homebrew needed):

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

By default, the standalone installer downloads from https://releases.openai.com/codex and falls back to GitHub Releases if a metadata or asset download is unavailable. To force GitHub Releases directly, set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false:

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

Option B — Homebrew cask:

brew install --cask codex

Option C — npm global install:

npm install -g @openai/codex

Linux (`x86_64` and `arm64`)

Option A — Official standalone script:

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

The script places the codex symlink in ${CODEX_INSTALL_DIR:-$HOME/.local/bin} and the standalone bundle in ${CODEX_HOME:-$HOME/.codex}/packages/standalone. If ~/.local/bin is not yet on your PATH, the installer updates your shell profile and prints the command to activate it in your current terminal:

export PATH="$HOME/.local/bin:$PATH" && codex

Option B — Direct GitHub Release .tar.gz binary (macOS & Linux):

Download the archive matching your CPU architecture from https://github.com/openai/codex/releases/latest:

macOS Apple Silicon (arm64): codex-aarch64-apple-darwin.tar.gz
macOS Intel (x86_64): 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

Each archive contains a single executable with the platform baked into its filename. After extracting, rename it to codex, make it executable, and place it in a directory on your PATH:

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
chmod +x ~/.local/bin/codex

Windows (PowerShell or WSL2)

Option A — Native PowerShell installer (verified 2026-10-18 from OpenAI's README):

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

To force the PowerShell installer to pull from GitHub Releases instead of releases.openai.com:

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

Option B — npm global install or WSL2: Run npm install -g @openai/codex in PowerShell, or open your Ubuntu 20.04+ / Debian 10+ WSL2 terminal and run curl -fsSL https://chatgpt.com/codex/install.sh | sh.

4. Verify with `codex doctor` & Manual `config.toml` Reference

After installing, confirm the active binary path and run codex doctor:

# Check version and every codex binary on PATH (macOS / Linux)
codex --version
which -a codex

# Run built-in installation, config, auth, and runtime health check
codex doctor

On Windows PowerShell, inspect the binary path with Get-Command codex and where.exe codex.

In real use (verified on an Apple Silicon Mac with codex-cli 0.163.0 on 2026-10-18), codex doctor checks three things:

Installation consistency & PATH order: Reports install consistent and flags duplicate binaries if an older Homebrew (/opt/homebrew/bin/codex) or npm copy appears earlier on PATH.
Authentication status: Before signing in or setting an API key, it prints auth ✗ no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
Configuration and endpoint reachability: Once ~/.codex/config.toml and its API key variable are set, it confirms config.load ok, auth is provided by the active model provider, and active provider endpoints are reachable over HTTP.

Manual `~/.codex/config.toml` Structure

If you prefer editing ~/.codex/config.toml ($CODEX_HOME/config.toml) manually instead of running the one-command uniroute-setup helper in the first section:

model = "MODEL_ID"
model_provider = "uniroute"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
env_key = "UNIROUTE_API_KEY"
requires_openai_auth = false

wire_api = "responses": Codex CLI communicates over OpenAI's Responses API protocol (POST /v1/responses) rather than Chat Completions (see OpenAI Responses API vs Chat Completions).
env_key = "UNIROUTE_API_KEY": Reads your key from the environment so you never hardcode secrets in config.toml.

5. How to Update or Uninstall Codex CLI

Update to the Latest Version

Per the official Codex CLI documentation (2026-10-27), re-running the standalone install.sh command updates an existing installation. You can also run codex update or your package manager's upgrade command:

# Built-in CLI updater
codex update

# If installed via the standalone script (official install & update command)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# If installed via npm
npm install -g @openai/codex@latest

# If installed via Homebrew cask
brew upgrade --cask codex

Uninstall Codex CLI

# If installed via npm
npm uninstall -g @openai/codex

# If installed via Homebrew cask
brew uninstall --cask codex

# If installed via install.sh (default paths)
rm -f "${CODEX_INSTALL_DIR:-$HOME/.local/bin}/codex" \
      "${CODEX_INSTALL_DIR:-$HOME/.local/bin}/codex-code-mode-host"
rm -rf "${CODEX_HOME:-$HOME/.codex}/packages/standalone"

Keep your ~/.codex configuration safe: ~/.codex (or $CODEX_HOME) stores config.toml, authentication state, and local session data. Back up ~/.codex/config.toml and ~/.codex/auth.json before switching install methods, and run plain brew uninstall --cask codex without --zap if you want to keep your configuration directory.

6. Frequently Asked Questions (FAQ)

Does Codex CLI need Node.js?

Only if you install it via npm install -g @openai/codex (which declares engines.node >= 16 in the @openai/codex@0.163.0 npm metadata). The official standalone installer (install.sh / install.ps1), the Homebrew cask (brew install --cask codex), and the GitHub Release archives install native binaries directly and do not require Node.js.

Is Codex CLI free?

The Codex CLI binary itself is open-source software under the Apache-2.0 License on GitHub. Running prompts requires either an eligible ChatGPT subscription (Plus, Pro, Business, Edu, or Enterprise) or pay-as-you-go API credits with OpenAI or a compatible API provider.

Can I install Codex CLI without administrator (`sudo`) rights?

Yes. On macOS and Linux, curl -fsSL https://chatgpt.com/codex/install.sh | sh installs into your home directory by default (~/.local/bin/codex and ~/.codex/packages/standalone), and you can override those paths with CODEX_INSTALL_DIR and CODEX_HOME.

Where is `config.toml` located?

Codex CLI reads its user configuration from ~/.codex/config.toml by default, or from $CODEX_HOME/config.toml when the CODEX_HOME environment variable is set.

How many tokens does a first Codex CLI smoke test use? (2026-10-18 verification note)

On 2026-10-18, we installed @openai/codex@0.163.0 on an Apple Silicon Mac (Node v22.23.3), verified config.toml with codex doctor, and ran a one-word non-interactive smoke test (codex exec --json --skip-git-repo-check --ephemeral -s read-only "Reply with exactly the word OK and nothing else."). It returned OK with exit code 0 and sent 15,761 input tokens (including 4,224 cached tokens) plus 5 output tokens because Codex CLI includes its system instructions and tool definitions in each request. Even a one-line test is not zero-token, so check your usage logs when testing with an API key.