Codex CLI Installation Guide (2026)

Goal

By the end of this guide you will have OpenAI’s Codex CLI installed and verified on macOS, Linux, or Windows, signed in, and ready to run its first safe task inside a Git project. You will also know how to update it, uninstall it, and what its most powerful mode can actually do to your files.

This guide covers installation only. For what local coding agents are and when to use one, see the local AI coding agents guide. For the equivalent Claude tool, see the Claude Code installation guide.

All time-sensitive claims below are marked: as of the last test date (2026-07-26). The install commands and account requirements change faster than most software, so re-check the official Codex CLI docs if you are reading this months later.

Background: why this guide changed

Codex CLI was originally written in TypeScript and distributed through npm. In 2025, OpenAI rewrote it in Rust, and the current tool ships as a standalone binary (GitHub README). Two practical consequences:

Node.js is no longer a real runtime requirement. You only need it if you pick npm as your install method.
There are now four official install paths, and the right one depends on your platform and habits.

Requirements

As of the last test date (2026-07-26), the official docs and README list:

Operating system: macOS 12+, Ubuntu 20.04+ / Debian 10+, or Windows 11.
An account: sign-in with a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan, or an API key (which requires extra setup). The free ChatGPT plan is not listed as supported (Codex CLI docs).
A terminal you are comfortable pasting commands into.
Git (recommended, not required) so you can see and undo whatever the agent changes.

Windows ambiguity — read this before installing. The install docs describe Windows support as “via WSL2,” while the GitHub README ships a native Windows PowerShell installer. Treat native Windows support as ambiguous official support: it exists in the README, but the docs still frame WSL2 as the supported path. If you hit strange behavior natively, retry inside WSL2 before blaming your setup.

Choose an install method

Your situation	Recommended method
macOS or Linux, no strong preference	Standalone install script
macOS with Homebrew already installed	`brew install --cask codex`
Windows 11, native	PowerShell install script
You already manage tools with npm	`npm install -g @openai/codex`
Windows long-term web development	WSL2 + the Linux script

The binary installed is the same; the methods differ in how updates and uninstalls work later. Pick one and remember which you picked — you will need it in the update and uninstall sections.

Install per platform

macOS / Linux: standalone installer (current recommendation)

From the GitHub README:

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

This downloads the install script and pipes it into your shell. Piping a remote script into sh executes whatever the server returns, so only do this with the official URL from OpenAI’s own repository — not a copy from a blog post, including this one. When in doubt, open the README and copy the command from there.

Windows 11: PowerShell installer

From the GitHub README, in PowerShell:

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

irm (Invoke-RestMethod) downloads the script and iex (Invoke-Expression) runs it. Same trust rule as above: use the URL exactly as it appears in the official README. If the result misbehaves, remember the WSL2 ambiguity noted in the requirements section.

npm (any platform with Node.js)

npm install -g @openai/codex

Package-name warning. The official package is @openai/codex. The plain codex package on npm is an unrelated old package. If you typed npm install -g codex, uninstall it (npm uninstall -g codex) and install the scoped package instead.

Even with the Rust rewrite, the npm distribution still works — npm is just the delivery mechanism, not the runtime.

macOS: Homebrew

brew install --cask codex

Note the --cask flag. Codex CLI is distributed as a Homebrew cask (a prebuilt binary), not a formula. brew install codex without --cask resolves to a different, unrelated formula — the same naming trap as npm.

Verify the installation

Whichever method you used:

codex --version

You should see a version number. As of the last test date (2026-07-26), the latest published version is 0.145.0, per the npm package page. If yours is older, see the update section below; the CLI also self-updates on startup.

If you get command not found, jump to common errors.

Enter a project folder and start the tool:

cd my-first-website
codex

On first run, Codex prompts you to authenticate. As of the last test date (2026-07-26), the two paths listed in the official docs are:

ChatGPT account sign-in — for Plus, Pro, Business, Edu, or Enterprise plans. The CLI opens a browser flow; complete it and return to the terminal.
API key — requires extra setup on the OpenAI platform side. If you go this route: never paste the key into a chat window, never commit it to Git, and if you store it in a .env file, make sure that file is in your .gitignore.

The free ChatGPT plan is not listed as a supported sign-in option as of the last test date.

Approval modes and safe first tasks

Permissions are the part of Codex CLI that decides what the agent may do to your machine. The exact interface wording shifts between versions, but the choices fall into three broad groups.

Read-only

Codex can inspect the project, explain code, and propose changes, but does not edit files or run state-changing commands. Use this the first time you open any project:

Please read this project and tell me what framework it uses, where the page directory is, and where the content files live. Do not modify any files.

Auto

Codex can do common development work — edit files, run build checks — while pausing on actions it considers significant. Reasonable for small, reversible tasks:

Please add a simple About page and run a build check.

Build one habit here: run git status and git diff after every task, before you accept anything.

Full Access

Codex edits files and runs commands with minimal confirmation. Do not start here. Consider it only when all of these are true:

The project is managed with Git and you know how to inspect and revert changes.
The task touches no private files, secrets, or production data.
You could recover the machine state if something goes wrong.

Safe first tasks (implementation checklist)

Work through these in order, inside a throwaway or Git-managed practice folder:

Run codex --version — confirms the binary works.
In Read-only mode, ask it to explain the project structure.
In Auto mode, ask it to make one small edit (a new page or a typo fix).
Run git status and git diff; confirm only the expected files changed.
Ask it to run the project’s build or test command; confirm the output yourself.
Only then consider larger tasks.

For a full practice project, continue with Build a Personal Website with AI.

Update Codex CLI

As of the last test date (2026-07-26), the CLI self-updates on startup. To update manually, use the same method you installed with:

# Standalone installer: re-run the script
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew cask
brew upgrade codex

# npm
npm install -g @openai/codex@latest

After updating, run codex --version again to confirm.

Uninstall Codex CLI

Uninstall is not officially documented as of the last test date (2026-07-26) — this is a gap in the official docs, so treat the steps below as editorial guidance, not an official procedure. The safe approach is to remove it through the method you installed with:

# Homebrew cask
brew uninstall --cask codex

# npm
npm uninstall -g @openai/codex

# Standalone installer: delete the installed binary
# (check where your shell resolves it first)
which codex

User configuration and sign-in state live in ~/.codex/. Deleting that folder removes your local settings; leave it in place if you plan to reinstall.

Common errors

`codex: command not found`

You installed the wrong npm package. npm list -g @openai/codex should show the package; if npm list -g codex shows one instead, you installed the unrelated old package — uninstall it and install @openai/codex.
With Homebrew, check you installed the cask: brew list --cask codex.
With the standalone installer, the install directory may not be on your PATH. Open a new terminal window first; if that does not help, re-run the installer and read its final output, which says where it placed the binary.

Installed `codex` but it is not OpenAI’s tool

Both npm (codex vs @openai/codex) and Homebrew (formula vs cask) have a same-name collision. If codex --version prints something unexpected or the tool behaves like a different program, uninstall it and reinstall using the exact commands above.

Windows: works in one terminal, not another

PowerShell, Windows Terminal, Git Bash, and WSL are separate environments with separate PATHs. Run codex in the same environment where you installed it. And recall the support ambiguity: if the native Windows install misbehaves, the docs’ supported path is WSL2 — install the Linux script inside WSL and work from there.

Confirm your plan is one of the listed supported tiers (Plus, Pro, Business, Edu, Enterprise) — the free plan is not listed as of the last test date.
For API keys, confirm the key is active on the OpenAI platform and that no stray whitespace or quotes were pasted with it.
Never “fix” auth problems by pasting your key into an AI chat window or committing it to a repository.

npm `EACCES` permission errors

Do not reach for sudo npm install -g. That creates root-owned files in your npm prefix and worse problems later. Follow the npm docs on resolving EACCES errors, or sidestep npm entirely with the standalone installer.

Safety notes: what Full Access can do

Risk note. In Full Access mode, Codex CLI runs shell commands with your user permissions and minimal confirmation. That means it can, in principle, do anything you can do in that terminal: delete files outside the project, exfiltrate anything readable by your user (SSH keys, browser cookies, .env files), install software, or push to remote git repositories. Approval modes are the only brake — the model’s good intentions are not a security boundary.

Practical rules:

Default to Read-only in unfamiliar projects and Auto for routine work.
Reserve Full Access for Git-managed, non-sensitive projects where a mistake is fully reversible.
Never run Full Access in your home directory, a documents folder, or a repo with uncommitted secrets.
git status and git diff after every task are your audit trail — use them.

When this guide does not apply

You want Codex in the cloud or the IDE. This guide covers the terminal CLI only. OpenAI ships other Codex surfaces (web, IDE extension); their setup lives in the Codex docs and is out of scope here.
You are on an older TypeScript-era install. Pre-Rewrite versions behaved differently. Uninstall your old copy and install fresh with the commands above rather than trying to upgrade across the rewrite.
You have not picked a coding agent yet. Installation is the easy part; choosing between agents is the real decision. Start with the local AI coding agents guide and the Claude Code installation guide to compare.

FAQ

Is Codex CLI free to use?

As of the last test date (2026-07-26), the official docs list sign-in with a paid ChatGPT plan (Plus, Pro, Business, Edu, or Enterprise) or an API key, which requires extra setup. The free ChatGPT plan is not listed as supported.

Do I need Node.js to run Codex CLI?

No. Codex CLI was rewritten from TypeScript to Rust in 2025, so it ships as a standalone binary. You only need Node.js and npm if you choose npm as your install method.

How do I update Codex CLI?

The CLI self-updates on startup. You can also re-run the official install script, run brew upgrade codex for the Homebrew cask, or run npm install -g @openai/codex@latest for the npm install.

Is the codex package on npm the right one?

No. The official package is @openai/codex. The plain codex package on npm is an unrelated old package — installing it will not give you OpenAI's coding agent.

Changelog

Jul 26, 2026: Full update for the Rust rewrite: added the standalone install scripts for macOS/Linux and Windows, the Homebrew cask method, update and uninstall steps, the npm package-name warning, and the Windows WSL2 vs. native installer discrepancy. Removed Node.js as a hard prerequisite.
May 8, 2026: Initial publication.