How to Install OpenAI Codex CLI (Windows, macOS, Linux)

- Commands and doc paths were cross-checked against the official docs at the time of writing (08/2026); Codex's docs domain has already moved once (developers.openai.com → learn.chatgpt.com), so verify the live docs before running these if this page is old.

Before you install Codex CLI

Before you install OpenAI Codex, line up these:

• A ChatGPT plan that supports Codex. Per the pricing page at the time of writing, CLI access is clearest from Plus and up (Plus, Pro, Business, Enterprise) or pay-as-you-go via an API key; Free/Go may not include it - check Codex pricing before you install instead of guessing.
• An OS: Windows, macOS, or Linux - Codex CLI runs natively on all three, no WSL2 required on Windows, and no separate build for Apple Silicon vs Intel to think about (the installer picks the right binary for you).
• A working connection to chatgpt.com to fetch the installer and sign in - a captive corporate proxy or a locked-down network can block the download even if the rest of your internet works fine.
• Node.js only if you pick the npm install path - the other two methods (install script, Homebrew) don't touch Node.

Line these four up and the actual install is one command plus a short download wait - the part that usually takes longer is picking the right ChatGPT account to sign in with, especially if you have both a personal account and a company-issued one (Business/workspace). The two can carry different CLI entitlements, so if a sign-in prompt looks unfamiliar or the CLI reports a plan you didn't expect, check which account you're actually authenticated as before assuming something is broken.

Install Codex CLI on macOS and Linux

The fastest path is the official install script, run directly in a terminal - it pulls down a native binary, no other runtime needed:

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

Piping curl straight into sh makes some people uneasy, and that instinct is reasonable in general - you're trusting whatever the URL returns at that moment. If you'd rather not run an unread script blind, download it first (curl -fsSL https://chatgpt.com/codex/install.sh -o install.sh), read it, then run sh install.sh. For a one-off install of a well-known vendor's official domain, most developers accept the risk; for a locked-down or shared machine, the download-then-read step is worth the extra minute.

Two alternatives if you'd rather manage it via a package manager:

brew install --cask codex

npm install -g @openai/codex

The most common trap: the npm package name is @openai/codex, not plain codex - running npm install -g codex installs the wrong package (or 404s). Two of the EN guides I read both flag this exact mistake. If you go the npm route, use a current Node.js LTS release; the secondary sources I cross-checked don't agree on the exact minimum version, so if npm throws a version error, update Node to the latest LTS first, or sidestep the whole question with the install script or Homebrew above. Check the official README on GitHub if you need to double-check.

Which one should you pick? If this is a one-time install and you don't care about manual updates, use the install script - it's the fastest. If your machine already leans on Homebrew for every other CLI, stick with that habit (a later brew upgrade updates Codex too). The npm path only makes sense if you already have Node.js installed for something else - don't install Node just to run this branch.

Install Codex CLI on Windows

On Windows, open PowerShell and run this exact command - I ran this live on my own Windows machine while writing this:

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

1. Open PowerShell (Administrator rights aren't required on most machines).
2. Paste the full command above and press Enter.
3. The -ExecutionPolicy ByPass flag applies only to this one run - it doesn't change your machine's policy - it just allows this unsigned install script to run this one time.
4. Close the old terminal and open a new one so the updated PATH takes effect.
5. Run codex --version to confirm.

Prefer Windows Terminal over the legacy cmd.exe window if you have it installed - it's not required, but the PowerShell prompt and any color output Codex prints render more reliably there, and it's what I used for the live run above.

Codex CLI runs natively on Windows - WSL2 is not required. If your team has already standardized on WSL2 (say, to share scripts with a Linux CI pipeline), you can still install Codex inside WSL2 using the same curl command from the macOS/Linux section above; there's no separate Windows-specific WSL2 command.

If your Windows machine is company-managed (a device under group policy), -ExecutionPolicy ByPass can still be blocked at the organizational policy layer, not just the user layer - in that case IT needs to relax it, and there's no user-side workaround. Windows Defender SmartScreen may also prompt you to confirm the first time you run a freshly downloaded installer - that's a normal warning for a new file, not a sign anything is broken.

Verify the install

Run codex --version. A version number printed back means you're done. If the terminal says codex isn't recognized, it's almost always a stale PATH - fully close the terminal (including an IDE's integrated one) and open a fresh window before suspecting anything else. If you tried more than one install method (say, npm and then the install script), and codex --version prints an unexpected version, you likely have two copies on PATH - check which one actually runs with where codex (Windows) or which codex (macOS/Linux), then remove the extra one.

Sign in to Codex

Run codex in your terminal to launch the CLI, then pick the ChatGPT sign-in option when prompted (the exact on-screen wording can shift between releases - follow what the CLI shows you at the time). The flow usually opens a browser tab for you to confirm the sign-in, then hands the session back to the terminal automatically - no manual token pasting. Your ChatGPT plan determines which model and usage limits you get; see Codex pricing by plan for the specifics instead of guessing numbers here. If sign-in fails silently (the browser tab closes but the terminal never confirms), the most common cause is a corporate SSO or proxy layer intercepting the redirect - try again on an unrestricted network before assuming the CLI itself is broken.

Run your first Codex command

cd into a real project folder (not an empty one - Codex needs actual code to read and work with), then run:

codex

Try something concrete, like: "Read the README and list 3 ways to run tests in this repo." Or something smaller to warm up: "List the 5 largest files in this repo by line count." If Codex needs to run a command or edit a file, it'll pause and ask for approval first (depending on your approval_policy) and show you the exact command or diff it wants to run so you can approve or reject it - that's the normal approval flow, not an error; the config section below explains why it stops and how to loosen or tighten that. A working first run typically ends with Codex printing a short summary of what it read or changed, plus any next-step suggestion - if you instead get an immediate error before it does anything, that almost always points back to the sign-in step above, not to this step.

~/.codex/config.toml basics

Your user config lives at ~/.codex/config.toml; a project can override it via .codex/config.toml at the repo root. Precedence (highest to lowest, per the official config docs): CLI flags > project .codex/config.toml > profile (--profile) > user ~/.codex/config.toml. In practice that means: if your personal ~/.codex/config.toml sets approval_policy = "on-request" as a sane global default, but a specific repo's .codex/config.toml sets approval_policy = "untrusted" for a stricter workflow, the project file wins whenever you're working inside that repo - and a one-off --approval-policy CLI flag beats both, for a single run.

These three are the ones worth tuning first: model trades off quality, speed, and cost; sandbox_mode decides what Codex can actually touch (there's also a safer read-only option and a danger-full-access one you shouldn't run as the default); approval_policy decides how often you have to manually approve. Put all three in one ~/.codex/config.toml and it looks like this:

model = "gpt-5.6"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

This is just the basic layer. The next layer - teaching Codex your project's own conventions (test/build commands, must-not-break rules) - lives in AGENTS.md for Codex.

Common install errors and fixes

Most install problems trace back to one of four things: a typo'd package name, a stale PATH, Windows' default script policy, or a folder Codex can't cleanly resolve permissions for. Here's each, with the actual fix instead of a generic "reinstall and hope":

Note: two different "curl ... | sh" install commands

If you later run into instructions for curl -fsSL https://agentkit.best/install.sh | sh, that's a different tool entirely - AgentKit (the ak CLI), a paid kit installed on top of Codex or Claude Code, not part of Codex itself. The two commands look almost identical (same curl -fsSL <domain>/install.sh | sh shape), so if you save either one in notes or shell history for later, label it with the domain - don't copy-paste one script thinking it's the other.

One more habit worth building early: Codex CLI ships fast, and both the install domain and some CLI flags have already changed once since launch. Re-running the install command every so often (or the update path for whichever method you used) is cheap insurance against quietly running a stale build.

Frequently asked questions

Is Codex CLI free to install?

The CLI itself is open source and free to install, and the binary doesn't expire or nag you. To sign in and actually use it, you need a ChatGPT plan that supports Codex (clearest from Plus and up, per the pricing page at the time of writing) or an API key billed by usage.

Do I need an API key?

Not if you sign in with a ChatGPT plan that supports Codex - that's the default path for most individual developers. An API key is only needed if you want to pay per token (useful for automation/CI, where signing in interactively isn't practical) instead of using a ChatGPT plan.

Can I install without Node.js?

Yes. The official install script (curl ... | sh on macOS/Linux, PowerShell on Windows) and Homebrew don't require Node.js at all. Only the npm install -g @openai/codex path needs Node, since npm itself ships with Node.js.

Does it need WSL on Windows?

No. Codex CLI runs natively on Windows, with its own installer and its own binary. WSL2 is only useful if you specifically want to share an existing Linux pipeline or shell scripts across your team.

How do I update it?

Re-run the same install method you used originally (the install script, brew upgrade, or npm install -g @openai/codex) and it overwrites the old version with the latest - there's no separate uninstall step needed first.

Add AgentKit after installing Codex?

Codex CLI itself is free (it rides on the ChatGPT plan you already have). AgentKit is a separate, paid layer you install on top of Codex to get prebuilt skills/subagents/workflows instead of assembling your own: ak kit init engineer --target codex --global, confirm the preview screen, open a new Codex session, then run $ak:cook ... to start. Nothing about that changes the base codex command you just installed - it just gives that command more structured things to run against. This is the same gate setup I actually run on both Claude Code and Codex, not a throwaway plug - the mechanics are covered in AgentKit in Codex. If you're just kicking the tires on Codex today, skip this step entirely and come back once you actually feel the friction of re-explaining your workflow every session - that's the point where a prebuilt kit starts paying for itself.