The most important part of installing Codex CLI isn't pasting one command into the terminal. It comes down to three things: confirming the command comes from the official source, making sure the system can find codex, and checking that both the version and help output print correctly. Once all three pass, you have a reliable starting point for logging in, configuring an API Key, and everyday use.
This tutorial is organized by operating system, with install commands, verification steps, and common issues for each. All install commands come from the OpenAI Codex CLI official documentationand the AI Code With Codex terminal documentation. If the commands here differ from what you see on the official pages, go with the official pages, because install methods change as versions are updated.
Haven't downloaded the installer yet? The official download link is in “Codex Download”. Once it's installed, see “How to Use Codex”.
Pick a Route Before You Install
OpenAI currently offers four install paths: a standalone install script for macOS/Linux, a standalone install script for Windows, npm, and Homebrew. They all install the same Codex CLI. The difference is what each one depends on and how you upgrade later.
| Install method | Best for | Prerequisites | Upgrade method |
|---|---|---|---|
| Official install script (macOS/Linux) | Users who don't want to install Node.js | curl and a network that can reach the official address | Re-run the same install command |
| Official install script (Windows) | First choice for Windows users | PowerShell | Re-run the same install command |
| npm | Developers already using Node.js | Node.js 18+ and npm | npm install -g @openai/codex |
| Homebrew | macOS users who prefer brew | Homebrew | brew upgrade --cask codex |
If you're on a network in mainland China, the official install script can be unreliable to download. In that case, npm with a China mirror is usually smoother. The AI Code With docs use the npm route and require Node.js 18 or later.
macOS Installation Steps
Option 1: Official install script
Open Terminal and run the standalone install command from the official docs:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
When you need to upgrade, just run the same command again.
Option 2: Homebrew
If you already have Homebrew installed, you can use the cask the official docs provide:
brew install --cask codex
The upgrade command is:
brew upgrade --cask codex
Option 3: npm
First, confirm Node.js is installed and the version is 18 or higher:
node --version
npm --version
If you don't have Node.js yet, install it with Homebrew, as the AI Code With docs do:
brew install node
Then install Codex CLI. Users in China can add the mirror parameter:
npm install -g @openai/codex
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
Pick one of the two commands. The second one uses the China mirror.
Verifying the macOS install
After installation finishes, open a new terminal window, then check in order:
command -v codex
codex --version
codex --help
The first command should print the path to codex, the second should print a version number, and the third should print the help text. If they do, the install succeeded. The bar for success isn't "the installer reported no errors." It's that all three commands produce normal output.
Windows Installation Steps
Option 1: Official PowerShell install script
The official OpenAI docs recommend that, from a newly opened PowerShell window, you run the following command:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Don't rely on PowerShell commands from old blog posts for long. The official install entry point gets updated, so check the official page for the current command before running it.
Option 2: npm
First download and install the LTS version from the Node.js website, then press Win + R, type powershell to open PowerShell, and check the version:
node --version
npm --version
Once you've confirmed Node.js is version 18 or higher, install Codex CLI:
npm install -g @openai/codex
Users in China can use the mirror instead:
npm install -g @openai/codex --registry=https://npmreg.proxy.ustclug.org
If PowerShell says "running scripts is disabled on this system," the AI Code With docs handle it this way: open PowerShell as administrator and run Set-ExecutionPolicy Unrestricted. This loosens the system's script execution policy, so make sure you understand the implications before doing it.
Verifying the Windows install
Close the current PowerShell window, open a new one, then check:
Get-Command codex
codex --version
codex --help
If Get-Command codex can't be found, don't reinstall yet. Read the section "Installed but can't find codex" below.
Linux Installation Steps
Option 1: Official install script
Linux uses the same standalone install command as macOS:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Option 2: npm
If Node.js isn't on your system yet, the AI Code With docs install it on Debian/Ubuntu like this (requires root):
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs
After confirming the version, install Codex CLI:
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
On other distributions, install Node.js LTS with your own package manager, then run the same npm commands.
Verifying the Linux install
command -v codex
codex --version
codex --help
If you're installing on a server with no GUI, the browser flow at the next login step may not work. How to handle that is covered in the common issues later on.
Why You Need to Reopen the Terminal Every Time
Many "installed but command not found" problems come down to a terminal that was never reopened. A terminal reads environment variables once at startup, so a new directory the installer adds to PATH only takes effect in terminal windows opened afterward. A window that's already open still uses the old PATH, so naturally it can't find the codex you just installed.
That's why the verification steps for every system in this article tell you to close the current window and open a new one before checking. If you installed from the built-in terminal in an editor like VS Code, you likewise need to quit the whole editor and reopen it. Opening a new terminal tab sometimes isn't enough.
Also, on Windows, if you switch between PowerShell, Command Prompt, and Git Bash, they may read different environment variables. Stick to PowerShell for both installing and using Codex, and troubleshooting gets much simpler.
Installed but can't find codex
This is the most common problem at the install stage. The cause usually isn't that it failed to install, but that the system PATH doesn't include the directory where Codex lives, or that the current terminal is still using old environment variables.
Check PATH first. On macOS / Linux:
command -v codex
printf '%s\n' "$PATH"
On Windows:
Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'
The suggested order: reopen the terminal first. If that doesn't help, confirm which directory the executable actually landed in (on the npm route, you can use npm prefix -g to see the global install location). Finally, add only that one directory to PATH.Don't add a directory of unknown origin to your system PATH wholesale.
Files Created After Installation
After you install and log in, Codex uses a config directory in your home directory, which defaults to ~/.codex (you can move it elsewhere with the environment variable CODEX_HOME). Two files matter most for beginners:
config.toml: Codex's config file, where settings like model, Provider, and permissions live;auth.json: the login cache. The official docs say Codex caches login info in this plaintext file, or stores it in the system credential store.
If you'd rather keep credentials in the system credential store than in a plaintext file, the official docs provide the cli_auth_credentials_store setting, and the possible values are file, keyring, auto, and ephemeral:file is stored in auth.json;keyring stores it in the system credential store, and errors out if the store is unavailable;auto prefers the credential store and falls back to auth.json if it's unavailable;ephemeral keeps it only in memory for the current process. The default is fine on a personal computer. On a shared machine, consider keyring.
Whichever route you take, keep this in mind: auth.json holds your access token, which makes it equivalent to a password. Don't commit it to a Git repository, paste it into a ticket, or post it in a group chat. When you share your configuration with teammates, send only config.toml, and first confirm that it doesn't contain any hardcoded keys.
Installing on a corporate network or behind a proxy
Many corporate networks route traffic through a TLS proxy or use a private root certificate. In that kind of environment, the install script may download fine, but the first login can fail with a certificate error. The officially documented fix is to set the environment variable CODEX_CA_CERTIFICATE to the path of the PEM certificate file provided by your company before logging in, and then run the login command:
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
If CODEX_CA_CERTIFICATE isn't set, Codex falls back to SSL_CERT_FILE. This certificate setting applies to login, regular HTTPS requests, and WebSocket connections, so setting it once covers all later calls. Ask your company's IT department for the certificate file, and don't download one from a random site.
Also, if you need a proxy to reach the outside internet, the npm route lets you configure npm's own proxy first, or switch to a regional mirror directly. That's usually less hassle than fiddling with system-wide proxy settings.
Uninstall the old version before switching install methods
If you started with npm and later want to switch to the official script or Homebrew, uninstall the old copy first. Otherwise, your PATH may find the old version first, and you'll end up in the situation where "I clearly upgraded, but the version number didn't change."
If you installed with npm, uninstall with npm:
npm uninstall -g @openai/codex
If you installed with Homebrew, uninstall with Homebrew:
brew uninstall --cask codex
After uninstalling, reopen your terminal and use command -v codex (on Windows, use Get-Command codex) to confirm the old command can no longer be found, then install with the new method. Uninstalling the CLI doesn't automatically delete the ~/.codex directory, so your configuration and login cache are still there and you can pick up right where you left off after reinstalling.
First launch and login
Go into a test project and start Codex:
cd /你的/测试项目
codex
On first run, the official docs say you can choose Sign in with ChatGPT or another available login method. The two common ones are:
- ChatGPT account login: Run
codex loginand finish signing in in the browser window that opens. This uses your subscription quota. - API Key login: The officially documented form is
printenv OPENAI_API_KEY | codex login --with-api-key, which is billed at standard API prices.
After logging in, you can use codex login status to check which authentication method is currently in use. Login information is cached locally in ~/.codex/auth.json or in your system credential store. That file is effectively a password, so don't commit it to Git or send it to anyone.
Connecting Codex with an AICodeWith API Key
Once Codex is installed, if you want to use an AICodeWith key to call models, follow the integration guide. This article doesn't repeat the configuration steps:
See the guide to connecting Codex to AICodeWith →
Common errors at a glance
| Error or symptom | Common cause | Fix |
|---|---|---|
| command not found: codex / Get-Command not found | The install directory isn't in PATH, or the terminal wasn't reopened | Reopen the terminal; use npm prefix -g to find the install location, and add only that one directory to PATH |
| npm: command not found | Node.js isn't installed, or Node.js isn't in PATH | Install Node.js LTS first, then confirm that node --version and npm --version both print output |
| Startup error after npm install; Node version too old | The AI Code With docs require Node.js 18+ | Upgrade Node.js to an LTS version and reinstall |
| PowerShell says "running scripts is disabled on this system" | Windows script execution policy restriction | In an administrator PowerShell, run Set-ExecutionPolicy Unrestricted (change it only after you understand the implications) |
| npm downloads are very slow or time out | The official npm registry is unreliable to reach | Add --registry=https://registry.npmmirror.com/ and other domestic mirrors |
| On a server, codex login can't open a browser | No GUI, or the local callback port localhost:1455 is blocked | Use codex login --device-auth device-code login, or forward port 1455 over SSH |
| Certificate errors when logging in on a corporate network | An enterprise TLS proxy or a private root certificate | Before logging in, set CODEX_CA_CERTIFICATE to point to a PEM certificate file |
| First launch shows "this folder is not version controlled" | The current directory isn't a Git repository, and Codex is confirming permissions | In a test directory, you can follow the prompt. For a real project, run git init first, then use |
If you hit a 401 or 429 after installation, that's not an install problem. See "How to Fix Codex 401 Unauthorized" and "How to Fix Codex 429 Too Many Requests" respectively.
FAQ
Does installing Codex CLI require Node.js?
Not necessarily. The official standalone install scripts (on macOS/Linux, install.sh; on Windows, install.ps1) don't depend on Node.js. You only need it if you go the npm route, and the AI Code With docs require Node.js 18 or later.
Which install method should I use on Windows?
Use the official PowerShell install script first. If you already work with Node.js, or the official script downloads unreliably, you can switch to npm with a domestic mirror. Both methods give you the same Codex CLI.
How do I upgrade Codex CLI?
Upgrade the same way you installed: rerun the install script, or for npm, run npm install -g @openai/codex again; for Homebrew, use brew upgrade --cask codex. After upgrading, run codex --version to confirm the version number changed.
Installation worked, but it asks me to log in on launch. Which option should I pick?
If you have a ChatGPT subscription, choose ChatGPT login, which uses your subscription quota. If you want pay-as-you-go billing or need to use it in CI, use an API Key. If you want to use an AI Code With key, sign up for an account first, then write the Provider configuration following the Codex configuration docs.
How do I log in on a Linux server with no GUI?
The officially recommended way is device-code login. Run codex login --device-auth, open the link on another device that has a browser, and enter the one-time code. You can also log in locally and copy ~/.codex/auth.json to the same location on the server.
Can I install multiple versions at the same time?
Not recommended. Mixing npm, Homebrew, and the install script makes it easy for PATH to find an old version first. Pick one method, uninstall the others, and then use command -v codex to confirm which one is actually being called.
Next Steps
Once it's installed, we suggest continuing in this order:
- "How to Use Codex: From Launch to Your First Verifiable Task": run through your first small task;
- "How to Configure the Codex API Key": connect an API Key and third-party Providers;
- "Codex config.toml Configuration Guide": learn where the config files live and how precedence works.
See the Codex and AICodeWith integration tutorial →



