Install and Update Codex CLI: Mac, Linux, Windows

Installing the OpenAI Codex CLI is one command per platform – curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS and Linux, powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" on Windows – with npm and Homebrew as the supported alternatives, and updating is codex update, which recognizes script, npm, and Homebrew installs and runs that channel’s upgrade.¹⁴¹¹ The part most pages skip is what comes after the first command: which of the five install routes to pick, how to pin a version when a release breaks you, why the winget package trails npm by seven minor versions, and what an uninstall leaves behind in ~/.codex. This page is that reference, one table per job, current as of v0.153.4 (September 4, 2026).⁹

TL;DR

• The standalone installer is the route OpenAI leads with in both the README and the CLI docs, with npm and Homebrew presented as alternatives (“you can also install” in the CLI docs, “can also be installed via” in the README): the install.sh script on macOS and Linux, the install.ps1 script on Windows. It downloads the compiled binary, so it needs no Node.¹¹¹
• npm and Homebrew are supported alternatives. npm install -g @openai/codex pins with a plain package spec (@<version>); brew install --cask codex was at the same 0.153.4 as npm when this was written.¹²¹⁰
• Avoid winget for installing Codex itself. OpenAI does publish the OpenAI.Codex package, but the manifest pull requests for 0.147.0 through 0.152.0 have sat unmerged in microsoft/winget-pkgs since August 7, 2026, so the newest installable version is 0.146.1 against npm’s 0.153.4 on the day of writing.³¹⁰
• codex update covers the script, npm, and Homebrew installs (v0.128.0 and later): it reuses the install-channel detection the TUI already has and runs the matching upgrade. A winget install is not a channel it recognizes; update that one with winget upgrade OpenAI.Codex. The manual equivalents for the rest are re-running the installer, npm install -g @openai/codex@latest, or brew upgrade --cask codex.⁴¹¹
• Pin with --release <version> on install.sh, $env:CODEX_RELEASE before the install.ps1 line, or @<version> on npm. Homebrew’s cask tracks one current version and cannot pin.²¹²
• Uninstalling the package does not remove your state, but on a script install rm -rf ~/.codex also deletes the CLI itself, because the installer keeps its releases under ~/.codex/packages/standalone.¹²

How Do I Install Codex CLI?

Four routes in the order OpenAI’s own docs present them,¹¹¹ plus winget on Windows, which OpenAI does not document:³

# Standalone installer, no Node required (macOS, Linux, WSL) -- the route OpenAI lists first
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

# npm (needs Node.js 16+; pins with a plain @version spec)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows; lags npm, see the platform section)
winget install OpenAI.Codex

Then confirm it landed and sign in:

codex --version      # codex-cli 0.153.4
codex login          # ChatGPT account (recommended) or an API key

On a first script install the profile block only takes effect in new shells. If codex is not found in the terminal you installed from, run export PATH="$HOME/.local/bin:$PATH" there or open a new one; the installer prints the same two lines (“Current terminal” and “Future terminals”) when it finishes.¹²

Prefer a raw binary? Every GitHub release ships platform tarballs (codex-aarch64-apple-darwin.tar.gz, codex-x86_64-apple-darwin.tar.gz, codex-x86_64-unknown-linux-musl.tar.gz, codex-aarch64-unknown-linux-musl.tar.gz), and since v0.106.0 the same install.sh is attached to each release as an asset. Each archive holds a single entry with the platform baked into its name, so rename it to codex after extracting.¹⁵

The installer fetches from OpenAI-hosted release infrastructure: chatgpt.com/codex/install.sh redirects to releases.openai.com, a change that landed in v0.146.0, with GitHub Releases kept as the fallback host.⁶ On a network that blocks or throttles OpenAI’s artifact host but allows GitHub, fetch the script from the release asset and tell it to pull the binary from GitHub too:¹¹²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

The variable goes on the sh side of the pipe. A VAR=value curl ... | sh form applies the variable to curl only, so the script never sees it and quietly keeps the default. In PowerShell, set $env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM = 'false' before running the install line.

Which route should you choose?

Which Platforms Does Codex Support?

On Windows, Codex runs natively in PowerShell with a Windows sandbox, and there are two sandbox modes. elevated is the preferred one: it uses dedicated lower-privilege sandbox users, filesystem permission boundaries, firewall rules, and local policy changes, and needs an administrator-approved setup. unelevated is the fallback: it runs commands with a restricted Windows token derived from your user and ACL-based filesystem boundaries.⁸ You select the mode in config.toml:

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

OpenAI’s guidance is to use the native sandbox by default and choose WSL when you need Linux-native tooling, when your workflow already lives in WSL2, or when neither native Windows sandbox mode meets your needs.⁸ One thing to keep straight: the Windows setup assumes winget is present on the machine for its own setup steps; that is separate from installing Codex through winget. OpenAI does publish that package – the release workflow has a winget job that opens a manifest pull request in microsoft/winget-pkgs for stable releases – but those submissions have been sitting unmerged since the 0.146.1 manifest merged on August 7, 2026; the requests for 0.147.0 through 0.152.0 were all still open when this was written, and no request exists for 0.153.0 through 0.153.4 at all. Nothing about the CLI is broken; the package index is behind.³⁸

Node.js is only a requirement for the npm route. The install scripts download the compiled binary, and the Homebrew cask declares no dependencies.¹²

How Do I Update Codex CLI?

Codex does not update itself. The TUI notices a newer release and offers the command for your install channel; running it is on you, and the built-in one covers the script, npm, and Homebrew installs.⁴ The startup check itself is a config key: check_for_update_on_startup = false in config.toml, which the reference describes as “Check for Codex updates on startup (set to false only when updates are centrally managed)”; fleets that manage updates centrally set features.in_app_updates = false in requirements.toml.¹⁶

codex --version                      # what you run now
npm view @openai/codex version       # newest published

codex update                         # built-in, v0.128.0+; detects your install channel

codex update arrived in v0.128.0 on April 30, 2026; the pull request that added it reused the install-channel detection and update runner the TUI already had for update prompts. The channel map covers npm (plus the bun, pnpm, and Vite+ variants), Homebrew, and the standalone installer on Unix and Windows; a winget install is not in it, so a winget-installed Codex updates through winget upgrade OpenAI.Codex only.⁴ The manual equivalents, if you prefer them or are scripting a machine image:

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # standalone: re-run the installer
npm install -g @openai/codex@latest                    # npm
brew upgrade --cask codex                              # Homebrew
winget upgrade OpenAI.Codex                            # winget (to whatever winget has)

irm https://chatgpt.com/codex/install.ps1 | iex           # standalone on Windows: re-run the installer

Releases land on a fast stable line – 0.150.0 through 0.153.4 shipped between August 26 and September 4, 2026 – so the gap between “what I run” and “newest” is often a week, not a quarter.⁹

How Do I Install a Specific Version?

npm and the install script both pin by version; Homebrew does not:²¹²

npm install -g @openai/[email protected]                                          # npm: exact version
curl -fsSL https://chatgpt.com/codex/install.sh | sh -s -- --release 0.152.1  # script: --release flag
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_RELEASE=0.152.1 sh    # script: env var, on the sh side
winget install OpenAI.Codex --version 0.146.1                                 # winget: only what it has
codex --version                                                               # verify the rollback took

Mind the placement in the env-var form: CODEX_RELEASE=0.152.1 must sit in front of sh, after the pipe. Written in front of curl, the variable applies to curl alone and the script installs latest while you believe you pinned.¹² On Windows the PowerShell script declares $Release = $env:CODEX_RELEASE as its only parameter and falls back to latest when it is empty, so the pin is the variable, set in the same session:¹⁷

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

Pinning is the right move when a release breaks you: file the issue, pin the last good version, move on. Verify with codex --version after every pin, because a second install elsewhere on your PATH keeps serving its own binary in silence. The install script checks for exactly this: when it finds a Homebrew-, npm-, or bun-managed codex already on your PATH, it warns that “Multiple managed Codex installs can be ambiguous because PATH order decides which one runs” and offers to run the matching uninstall for you.¹² codex doctor reports the same condition under Environment after the fact.⁷

How Do I Uninstall Codex CLI?

Remove it with the route that installed it:

npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

A script install has no package manager to ask. The installer puts a codex symlink in ~/.local/bin (override with CODEX_INSTALL_DIR) that points at the binary inside ~/.codex/packages/standalone/current (current/bin/codex on current releases); current is itself a symlink into ~/.codex/packages/standalone/releases/, where each downloaded release lives. On macOS the installer adds a second symlink, codex-code-mode-host, beside the first.¹² Remove all of it:

rm -f ~/.local/bin/codex ~/.local/bin/codex-code-mode-host   # the second link exists on macOS installs only
rm -rf ~/.codex/packages/standalone

If ~/.local/bin was not on your PATH when you installed, or the installer found a competing Homebrew, npm, or bun install and rewrote the entry, the script also appended a marked block to your shell profile: # >>> Codex installer >>> through # <<< Codex installer <<< in ~/.zprofile (macOS zsh), ~/.bash_profile, ~/.zshrc, ~/.bashrc, or ~/.profile. Delete those three lines to finish.¹²

On Windows, install.ps1 keeps the same layout under %USERPROFILE%\.codex\packages\standalone (or %CODEX_HOME%\packages\standalone if you set that variable): downloaded releases in releases\, a current junction pointing at the active one. It exposes codex.exe through %LOCALAPPDATA%\Programs\OpenAI\Codex\bin (override with CODEX_INSTALL_DIR), which is itself a junction into current\bin, and instead of a profile block it writes that bin path into your user PATH for future PowerShell sessions. Remove the standalone directory first, then the now-dangling bin junction, then take the entry back out of the user Path variable under Environment Variables:¹⁷

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\packages\standalone"   # releases plus the current junction
cmd /c rmdir "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin"                  # the bin junction; rmdir removes the link, not a target

The package-manager uninstalls above do not touch ~/.codex/. Homebrew’s --zap does not either, in practice: the cask’s only zap stanza is rmdir: "~/.codex", and Homebrew applies rmdir: only to directories that are already empty.² That directory holds config.toml, your stored credentials, and every session, which is why a reinstall picks up your login and history where you left them. Delete it only when you want a genuinely clean slate, and know what that means on a script install:

rm -rf ~/.codex   # discards config.toml, credentials, all sessions -- AND the CLI itself on a script install

A clean reinstall that keeps your state is one line on npm: npm uninstall -g @openai/codex && npm install -g @openai/codex@latest. On the script route, re-running the installer replaces the release under ~/.codex/packages/standalone and leaves your config alone.¹²

The Whole Lifecycle in One Table

What Does codex doctor Check?

codex doctor is the command to run before filing a bug or debugging an install that “worked yesterday.” On 0.153.4 it captures seven sections in one report – Notes, Environment (runtime and install consistency), Configuration (config.toml load status, auth, MCP, sandbox policy), Desktop App (added in v0.149.0), Updates, Connectivity, and Background Server – with --summary for a compact view, --json for a redacted machine-readable form, --all to expand truncated lists, and --no-color for logs; codex doctor --help on 0.153.4 also lists --ascii.⁷¹³¹⁵ Most “Codex is broken” reports resolve to something it names on the first screen: a stale auth mode, a config.toml that failed to parse, or a second install shadowing the one on your PATH. The full section-by-section breakdown lives in the guide.

What Changes After Install

The first thing a fresh install trips over is not the binary. Since v0.149.0 the CLI refuses to start on approval_policy = "untrusted", so a config.toml copied from an older machine needs one edit.¹³ Coming from Claude Code? The migration post maps the two configs side by side, and the hooks post covers what Codex runs around the model. The Codex CLI guide is the full reference: sandbox and approval modes, AGENTS.md, MCP, skills, and cloud tasks. And if you run both tools, the Claude Code install page is this page’s twin.

FAQ

How do I update Codex CLI to the latest version?

Run codex update (v0.128.0 and later); it detects whether you installed through the script, npm, or Homebrew and runs that channel’s upgrade. The manual equivalents are re-running the install script, npm install -g @openai/codex@latest, or brew upgrade --cask codex. A winget install is not a channel codex update recognizes; use winget upgrade OpenAI.Codex for that one.

Does Codex CLI update automatically?

No. The TUI checks for a newer release and offers the update command that matches your install channel, and codex update (v0.128.0 and later) runs it; nothing is downloaded or applied until you do.

How do I uninstall Codex CLI?

Use the route that installed it: npm uninstall -g @openai/codex, brew uninstall --cask codex, or winget uninstall OpenAI.Codex. For a script install, remove the ~/.local/bin/codex symlink (and ~/.local/bin/codex-code-mode-host on macOS) and the ~/.codex/packages/standalone directory. On Windows the script install is %USERPROFILE%\.codex\packages\standalone, the %LOCALAPPDATA%\Programs\OpenAI\Codex\bin junction, and an entry in your user PATH; remove all three. Your config, credentials, and sessions stay in ~/.codex/ until you remove the rest of that directory yourself.

How do I install Codex CLI on Windows?

Run powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". The CLI runs natively in PowerShell with a Windows sandbox (elevated preferred, unelevated as the fallback); WSL2 is an option when you need Linux tooling or neither sandbox mode fits, not a requirement. Windows 11 is the recommended baseline. winget install OpenAI.Codex also works but trails the stable line.

Do I need Node.js to install Codex?

Only for the npm route, and the package asks for Node 16 or later. The install script, the PowerShell script, and the Homebrew cask all provide the compiled codex binary, so a machine without Node can run Codex.

How do I check which version of Codex I have?

codex --version prints it (for example codex-cli 0.153.4). npm view @openai/codex version shows the newest published version, and codex doctor reports the install path and whether another copy on your PATH is shadowing it.