caprock

How to install Codex CLI on Mac, Windows and Linux

Run one command: curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS or Linux, or OpenAI's PowerShell installer on Windows. npm install -g @openai/codex and brew install --cask codex work too. Then run codex in your project and sign in with ChatGPT or an API key. Read 20 October 2026.

Dmitriy Solodukha · checked against Caprock v0.70.1

command installs it; the same command updates it
1
command installs it; the same command updates it
OpenAI's standalone installer
the latest stable Codex CLI
0.163.0
the latest stable Codex CLI
npm, Homebrew and GitHub Releases, read 20 October 2026
of RAM at least, 8 GB recommended
4 GB
of RAM at least, 8 GB recommended
macOS 12+, Ubuntu 20.04+, Debian 10+; Windows 11, or 10 1809+
a month for ChatGPT Plus, the first plan that lists the CLI
$20
a month for ChatGPT Plus, the first plan that lists the CLI
or an API key, billed per token

From OpenAI's Codex docs (CLI, authentication, Windows, troubleshooting) and the openai/codex README, read 20 October 2026. Plans from Codex pricing and usage.

Install Codex CLI

One command for your system

Open a terminal, paste the line for your shell, then open a new terminal window so it finds codex.

macOS, Linux, WSLTerminal

WindowsPowerShell

Any system with Node.jsnpm

The script installs to ~/.local/bin and adds it to your shell profile; on Windows it installs to %LOCALAPPDATA%\Programs\OpenAI\Codex\bin. No administrator rights needed. Prefer a window to a terminal? The ChatGPT desktop app and the Codex IDE extension run the same agent.

Installer, Homebrew, npm, binary

Pick your install

Every method installs the same codex program. They differ in how you update it.

Ways to install Codex CLI, from OpenAI's Codex docs and the openai/codex README, read 20 October 2026
MethodSystemsUpdateNeeds Node.js
Standalone installer (OpenAI's first choice)macOS, Linux, Windowsrun it again, or codex updateno
HomebrewmacOSbrew upgrade --cask codexno
npmmacOS, Linux, Windowsnpm install -g @openai/codexyes
Binary from GitHub ReleasesmacOS, Linux, Windows; x64 and ARM64download the new releaseno
Keep one. If two copies are installed, PATH order decides which one runs; on macOS and Linux OpenAI's installer finds an npm or Homebrew copy and offers to remove it. The GitHub binaries are named for the platform, such as codex-aarch64-apple-darwin.tar.gz: rename the extracted file to codex.

  1. Homebrew (macOS) — a cask, not a formula

  2. npm

Step by step

On Mac, Windows and Linux

macOS

  1. 1

    In Terminal, install

  2. Or with Homebrew

  3. 2

    Open a new window and check

  4. 3

    Start it in your project

Windows

  1. 1

    In a new PowerShell window, install

  2. Or with npm

  3. 2

    Open a new window and check

    Codex runs commands in its own Windows sandbox. OpenAI recommends MXC, which needs no administrator setup (prefer_mxc = true for the CLI); otherwise the CLI uses the elevated sandbox, whose one-time setup needs UAC approval.

  4. 3

    Start it in your project

Linux and WSL

  1. 1

    In your shell (in WSL, inside the distribution)

  2. 2

    Open a new shell and check

  3. 3

    Start it in your project

Codex on Windows: native or WSL?

OpenAI recommends native Windows with its own sandbox, and WSL 2 when your work already lives in Linux. In WSL you install and run codex inside the WSL terminal.

Codex CLI on Windows, native or in WSL, from OpenAI's Windows docs, read 20 October 2026
OptionRequiresSandboxWhen to use
Native WindowsWindows 11; Windows 10 1809+ best effortCodex's own Windows sandboxOpenAI's default
WSL 2WSL 2 and a Linux distributionthe Linux sandboxLinux toolchains, work already in WSL
WSL 1—not supported since Codex 0.115move to WSL 2

Sign in

ChatGPT account or API key

The first time you run codex it asks how to sign in. A ChatGPT plan bills through the plan; an API key bills every token.

How to sign in to Codex CLI and who bills you, from OpenAI's authentication docs, read 20 October 2026
Sign-inCommandWhat you pay
Sign in with ChatGPTcodex loginyour ChatGPT plan; Plus ($20 a month) is the first that lists the CLI
API keyprintenv OPENAI_API_KEY | codex login --with-api-keyevery token at OpenAI API rates; no cloud features
Over SSH, no browsercodex login --device-autha one-time code; turn device login on in ChatGPT's security settings first
Credentials are kept in ~/.codex/auth.json or your OS keychain; codex logout removes them. What each plan includes and its limits are in Codex pricing and usage.

Check it works

After you install

A version number means the install worked. If codex is not found, the install folder is not on your PATH yet.

  1. 1

    Prints the version

  2. 2

    Exits 0 when you are signed in

  3. 3

    Settings, logins and sessions live here

    config.toml is the settings file; sessions/ holds every conversation. CODEX_HOME moves the folder.

Troubleshooting

If the install fails

Find what you see. Each row is from OpenAI's Codex docs or its installer.

Codex CLI install and sign-in problems, cause and fix, from OpenAI's docs, read 20 October 2026
You seeWhyFix
command not found: codexthe install folder is not on PATH yetopen a new terminal; the installer adds ~/.local/bin
An old version still runsa second copy from npm or Homebrew is earlier on PATHrun which -a codex, remove the one you do not use
codex not found in WSLit was installed on the Windows sideinstall again inside the WSL terminal; keep repositories under ~/, not /mnt/c
WSL 1the Linux sandbox needs WSL 2 since Codex 0.115convert the distribution to WSL 2
Windows sandbox setup failsUAC declined, a policy, or error 1385turn on MXC with prefer_mxc = true under [features], or set sandbox = "unelevated" under [windows] in config.toml
The browser login never returnsa remote machine or containercodex login --device-auth, or tunnel port 1455 over SSH
Windows 10 terminal problemsbuilds older than 1809 have no ConPTYupdate Windows, or use WSL 2

Next

See what your Codex sessions cost

Codex writes every session to ~/.codex/sessions. Caprock, a free desktop app, runs Codex and Claude Code in terminal tabs per project, reads those files and shows each session live, with tokens and cost, side by side. Free, local, one download.

Download for Mac

Notarized by Apple. One file for Apple silicon and Intel, macOS 13 or later.

Or run it yourself:

curl -fsSL https://caprock.dev/mac.sh | sh

Paste in Terminal: it installs Caprock and opens it.Or with Homebrew: brew install --cask dspv/tap/caprock-app

Then open the app. It reads Codex, Claude Code, OpenCode and Gemini CLI, and can start a Codex session from its New session dialog. More in Codex pricing and usage.

The full guide

Install Codex CLI, step by step

Codex CLI is OpenAI's coding agent for the terminal, one program called codex. The commands above install it; this part covers what the installer leaves on your machine and how to remove it.

What the installer does

The standalone script downloads the release for your system from OpenAI, falls back to GitHub Releases, and puts codex in ~/.local/bin (on Windows, %LOCALAPPDATA%\Programs\OpenAI\Codex\bin). It adds that folder to your shell profile (on Windows, your user PATH), which is why a new terminal finds it and the old one does not. Run the same command later and it updates in place.

On macOS and Linux, if it finds a copy you installed with npm, Homebrew or bun, it offers to remove it. Keep one: with two installed, whichever folder comes first on your PATH wins, and codex --version can report a version you did not just install.

Where Codex keeps its files

Everything lives in ~/.codex, or in the folder CODEX_HOME names. That folder must exist before you point CODEX_HOME at it.

What is in ~/.codex, from OpenAI's config and troubleshooting docs.
PathWhat it holds
config.tomlsettings: model, approvals, sandbox, MCP servers
auth.jsonyour login, unless it is kept in the OS keychain
sessions/every conversation, one file per session, by date
archived_sessions/sessions you archived

A project can override settings with its own .codex/config.toml, read only once you trust the project.

Update or remove it

How to update and uninstall Codex CLI, by install method.
Installed withUpdateUninstall
Standalone installerrun it again, or codex updatedelete ~/.local/bin/codex and ~/.codex/packages/standalone
Homebrewbrew upgrade --cask codexbrew uninstall --cask codex
npmnpm install -g @openai/codexnpm uninstall -g @openai/codex
OpenAI's docs give no uninstall step for the standalone install. ~/.local/bin/codex is a link into ~/.codex/packages/standalone; on macOS also delete ~/.local/bin/codex-code-mode-host.

Removing the program leaves ~/.codex with your settings, login and history. Delete it only if you want them gone.

Where your sessions go

Codex writes every session to ~/.codex/sessions/ as JSON lines, with the tokens of each turn. Caprock reads that folder, and archived_sessions/, honouring CODEX_HOME, and shows each Codex session live next to your Claude Code ones, whichever terminal started it, priced at OpenAI's list rates — an estimate, not a bill. Its Cost screen also shows Codex's plan windows (5-hour and weekly, where your plan has them) as Codex last recorded them. What each plan includes, and what a session costs, is in Codex pricing and usage; how Codex compares with Anthropic's agent is in Codex vs Claude Code.

Questions people ask

How do I install Codex CLI?
On macOS or Linux run curl -fsSL https://chatgpt.com/codex/install.sh | sh. On Windows run OpenAI's PowerShell installer. npm install -g @openai/codex and brew install --cask codex work too.
Does Codex CLI work on Windows?
Yes, natively. OpenAI recommends native Windows with Codex's own sandbox, on Windows 11 or Windows 10 1809 and later, and WSL 2 when your tools live in Linux. WSL 1 is not supported since Codex 0.115.
Is Codex CLI free?
The program is free and open source. Using it needs a ChatGPT plan that includes Codex, Plus being the first that lists the CLI, or an OpenAI API key billed per token.
How do I update Codex CLI?
Run the install command again, or codex update. Homebrew installs update with brew upgrade --cask codex, and npm installs with npm install -g @openai/codex.
How do I uninstall Codex CLI?
npm uninstall -g @openai/codex or brew uninstall --cask codex. For the standalone install, delete ~/.local/bin/codex and ~/.codex/packages/standalone. Settings, logins and sessions stay in ~/.codex until you delete it.

Sources

Try it

The record of every coding agent you run, the sessions it did not start included. Free, open source; nothing leaves your machine.

Download for Mac

Notarized by Apple. One file for Apple silicon and Intel, macOS 13 or later.

Or run it yourself:

curl -fsSL https://caprock.dev/mac.sh | sh

Paste in Terminal: it installs Caprock and opens it.Or with Homebrew: brew install --cask dspv/tap/caprock-app