SU8 Codes
< Back to blog
Official article Updated 4 min read

How to Install Codex CLI

Install Codex CLI on macOS or Linux with the official installer, or with npm. The installer was tested on macOS and Ubuntu, npm on Ubuntu (0.169.0); Windows and Homebrew weren't tested.

#codex#install
How to Install Codex CLI

To install Codex CLI on macOS or Linux, run the official installer:

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

Then run codex --version. If it prints a version number, the install worked. Next steps (sign-in, config.toml, daily commands) are in the Codex CLI tutorial; if you're still choosing a tool, see how the main AI coding agents compare.

What was tested: on November 14, 2026, the official installer was run with Codex CLI 0.169.0 on macOS and Ubuntu, and the npm install on Ubuntu. Homebrew, Windows, and codex update weren't tested; those commands follow the official docs.

Install options at a glance

OptionInstallUpgrade
Official installer (macOS/Linux)curl -fsSL https://chatgpt.com/codex/install.sh | shRerun it
npmnpm install -g @openai/codexRerun it
Homebrew (not tested here)brew install --cask codexbrew upgrade --cask codex
Windows PowerShell (not tested here)powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Rerun it

Install Codex CLI on macOS and Linux

The installer detects your OS and CPU and downloads the matching standalone package. Test results from November 14, 2026:

  • macOS 26.5.2 (Apple Silicon): done in about 15 seconds; codex --version printed codex-cli 0.169.0.
  • Ubuntu 22.04 (x86_64): detected Linux (x64) and installed the 0.169.0-x86_64-unknown-linux-musl package. It ended with:
==> Current terminal: export PATH="~/.local/bin:$PATH" && codex
==> Future terminals: open a new terminal and run: codex
==> PATH was added to ~/.bashrc
Codex CLI 0.169.0 installed successfully.

Install Codex CLI with npm

npm install -g @openai/codex

This suits machines that already use npm to manage command-line tools. On Ubuntu with Node.js 22.17, it also installed 0.169.0 in the November 14 test.

Install Codex CLI on Windows (not tested)

The docs offer two routes, and neither was tested for this guide:

  1. Native: run the PowerShell command from the table above.
  2. WSL2: install Linux with wsl --install, then use the Linux installer inside WSL.

From the official WSL page:

  • WSL1 is unsupported from 0.115 onward, because the sandbox moved to bubblewrap. Use WSL2.
  • Keep repositories in your Linux home, such as ~/code/my-app, not under /mnt/c. The page says this gives faster I/O and fewer symlink and permission issues.

Verify the install

codex --version
codex doctor

According to the docs, codex doctor checks installation, configuration, authentication, runtime, Git, and terminal health.

Key lines from the macOS test:

  • Codex Doctor v0.169.0 · macos-aarch64
  • ✓ install consistent
  • install method standalone
  • executable ~/.local/bin/codex

With no key set, it also flagged missing auth in its Notes.

Sign in

The first time you run codex in a project, it asks how to sign in. You can also do it directly:

# ChatGPT account (opens a browser)
codex login

# API key, billed at standard API rates
printenv OPENAI_API_KEY | codex login --with-api-key

# Check the current state
codex login status

In the Ubuntu test, codex login status printed Not logged in and exited with code 1 when no one was signed in, so scripts can check it.

Credentials are cached in ~/.codex/auth.json or your OS credential store. codex logout clears them.

Update Codex CLI

Rerun the install command you used. codex --help also lists codex update. Per the docs, it checks for and applies an update when the installed release supports self-update. It wasn't tested here.

Troubleshooting

codex: command not found after the official installer. The binary is at ~/.local/bin/codex, and that folder needs to be on your PATH. In the Ubuntu test, the installer added it to ~/.bashrc and printed the command to run in the current terminal. For other shells, follow the installer's final message.

curl: (22) The requested URL returned error: 403 from the installer. The download request was refused. If you hit this, this guide has no workaround to offer.

Codex doesn't work in WSL (not tested here). Check that you're on WSL2. WSL1 is unsupported from 0.115 onward.

FAQ

npm or the official installer?

The installer sets up a standalone package; npm installs the npm package. Both produced 0.169.0 in the November 14 test. If you already manage tools with npm, use npm.

What do I do after installing?

Open a project folder and run codex. The official quickstart suggests "Tell me about this project" as a first prompt, plus a Git checkpoint, such as a commit, before and after each task so you can revert. The Codex CLI tutorial covers approval modes and config.toml from there.