Codex CLI install: the complete guide for macOS, Windows, and Linux

Install Codex CLI on macOS, Windows, WSL, and Linux. Compare the official installer, npm, Homebrew, and binaries; verify, sign in, fix PATH errors, update, or uninstall.

Codex CLI install: the complete guide for macOS, Windows, and Linux

If you searched for codex install, codex CLI install, install codex CLI, npm install codex, or a codex CLI download, you probably want one thing: a working codex command in the terminal you already use. This guide covers the official installer, npm, Homebrew (brew install codex), release binaries, native Windows, Windows Subsystem for Linux (WSL), first login, updates, removal, and the errors that most often make an installation look broken.

Checked 2026-09-23. Codex CLI commands and requirements can change. Confirm the current instructions in the official Codex repository and installation guide before installing on a managed or production machine.

Choose an install method

These methods install the same Codex CLI project. Pick one method for a given shell so that you know which installation to update or remove.

Before you install

The current official installation guide lists macOS 12 or newer, Ubuntu 20.04 or newer, and Debian 10 or newer. Its supported Linux and macOS shell installer is the quickest route. On Windows, the current CLI has a native installer; Official materials also describe WSL 2 for a Linux-based development environment. WSL 1 is not supported by the current WSL guide.

The npm package requires Node.js. The current package manifest lists Node.js 16 or later, but a newer supported LTS release is usually a better starting point for a new Node installation. If npm reports an engine requirement, follow the requirement shown by the package manager at install time. You do not need Node.js when using Homebrew, the platform installer, or a release binary.

If you are using a work-managed computer, check your organization’s software policy before running an installer or changing shell startup files.

Install on macOS or Linux

Official installer

Open Terminal (or your Linux shell) and run the official installer:

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

The command downloads and runs the installer published by official materials. If you prefer not to pipe a downloaded script directly to a shell, open the official Codex repository and follow its release and installation instructions for your platform.

Homebrew on macOS

If you use Homebrew, the official repository documents this cask command:

brew install --cask codex

npm

If you already maintain global command-line tools with npm, install the scoped package:

npm install -g @openai/codex

The package name includes the @openai/ scope. npm install codex is not the command shown by the official Codex repository; use @openai/codex to install Codex CLI.

Download a release binary

The official GitHub releases provide platform-specific binaries. Choose the artifact matching both your operating system and CPU architecture (for example, Apple silicon versus Intel on macOS, or x86-64 versus ARM64 on Linux). Follow the release notes for the selected version and put the executable in a directory already on your PATH.

Install on Windows

Native Windows terminal

In PowerShell, run the official Windows installer command from the Codex repository:

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

Close and reopen PowerShell after installation so it reloads the updated environment. The native command is useful when your project and tooling are Windows-native.

Windows Subsystem for Linux

Choose WSL when your project uses Linux tools or you want the CLI to run inside a Linux environment. Install a distribution with WSL 2 if you do not already have one, then launch it:

wsl --install
wsl

Inside the WSL shell, install Codex as a Linux program:

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

Keep Linux projects in the WSL filesystem, such as ~/code/project, rather than under /mnt/c when possible. The official WSL guide recommends this for faster file access and fewer permission or symlink problems. Install Codex separately in Windows and in WSL if you use both; they have separate shells, PATH values, and configuration directories.

Verify the installation and sign in

Open a new terminal window and check that the command resolves:

codex --version

On macOS or Linux, which codex shows the executable selected by that shell. In PowerShell, use:

Get-Command codex

Then start Codex and choose the sign-in option shown by the CLI:

codex

You can also start the browser sign-in flow with codex login. ChatGPT sign-in uses the account flow offered by Codex. API-key authentication is billed by API usage and is separate from ChatGPT plan usage. Official documentation describes API-key login with printenv OPENAI_API_KEY | codex login --with-api-key; treat the key as a secret and do not paste it into a repository or share it in terminal logs.

Where Codex keeps its configuration

The user-level configuration file is ~/.codex/config.toml on macOS and Linux. A project may also contain .codex/config.toml; Codex uses project configuration only for trusted projects. Read the official configuration basics before adding project-specific settings. Keep secrets in environment variables rather than TOML files.

Common installation errors

codex: command not found or “not recognized”

First open a new terminal. Then check whether the install directory is on that shell’s PATH (which codex on macOS/Linux; Get-Command codex in PowerShell). If you installed with npm, check npm prefix -g and ensure that npm’s global executable directory is on PATH. For the official installer, follow the printed instruction for adding its install directory to your shell profile. In WSL, run the check inside WSL; Windows PowerShell and WSL do not share the same PATH.

npm says the Node version is unsupported

Check node --version, then update Node.js using the version manager or installer you normally use. Open a new shell after changing versions and retry npm install -g @openai/codex. Avoid using sudo npm install -g as a routine fix; it can leave global packages owned by a different user. Prefer a Node version manager or repair the npm global prefix permissions for your user.

Permission denied during installation

For npm, check that your configured global package directory is writable by your account. For a downloaded binary, confirm that it is for your operating system and architecture and that your account can execute it. Follow the operating system’s normal security prompt and your organization’s policy; do not solve the problem by making broad system directories writable.

The command works in one terminal but not another

You may have installed in a different shell, under a different user, or in WSL rather than Windows. Run Get-Command codex in PowerShell and which codex inside WSL or a Unix shell. Also check which install method you used, since a Homebrew-managed executable and an npm-managed executable have different update paths.

The installer does not match the computer

Check the CPU architecture and choose the corresponding release asset. On Linux, also confirm that the distribution is within the supported range in the current installation guide. On Windows, decide whether you want the native Windows CLI or the Linux CLI inside WSL; do not troubleshoot one from the other shell.

Update Codex CLI

Update Codex using the same tool that installed it:

# npm
npm install -g @openai/codex

# Homebrew
brew upgrade --cask codex

For the official installer, rerun the current installer command or use the update guidance in the official repository. For a manually downloaded binary, download the release you want and replace the executable following that release’s instructions. Check codex --version afterward. On Windows and WSL, update the installation in the shell where you run it.

Uninstall Codex CLI

Use the package manager that owns your installation:

# npm
npm uninstall -g @openai/codex

# Homebrew
brew uninstall --cask codex

For the shell or PowerShell installer, follow the current removal instructions in the official repository; remove only the Codex executable and installer-managed files you recognize. A release binary can be removed by deleting that binary. Your ~/.codex configuration and sign-in data are separate from the executable, so inspect them before deciding whether to remove them too.

If you hit a plan limit: use a custom API endpoint

Codex can be configured with a custom model provider. This is an option for people who need usage-based API access after reaching a ChatGPT plan limit. It is a separate billing path: API usage is charged by the API provider, and API-key use may not include every ChatGPT workspace or cloud feature. Check the official authentication and advanced configuration guides, and confirm the model and workflow you need are available before switching.

For an API-compatible endpoint, a user-level ~/.codex/config.toml can contain:

model = "gpt-5.3-codex"
model_provider = "bazaarlink"

[model_providers.bazaarlink]
name = "BazaarLink"
base_url = "https://api.bazaarlink.ai/v1"
env_key = "BAZAARLINK_API_KEY"
wire_api = "responses"

Set BAZAARLINK_API_KEY in your shell environment; never put its value in this file. For example, PowerShell uses $env:BAZAARLINK_API_KEY = "your-key" for the current session, and a Unix shell uses export BAZAARLINK_API_KEY="your-key". Get a key only through your account and keep it private. The model name above is listed in BazaarLink’s live model catalogue; catalogue entries and rates can change.

If you are still setting up the CLI, our Codex CLI tutorial in Traditional Chinese covers a complementary configuration and usage walkthrough. For broader cost context, see subscription versus usage-based API billing.

Quick checklist

• Install with one method that matches your operating system and shell.
• Open a fresh terminal and confirm codex --version and the executable path.
• Sign in with ChatGPT or explicitly choose usage-based API authentication.
• Keep API keys in environment variables.
• Update or uninstall with the same package manager that installed Codex.
• Recheck the official install and configuration pages because commands and supported options can change.

Official references

• Codex CLI repository and install methods
• Codex installation requirements
• Codex on Windows with WSL
• Codex authentication
• Codex configuration basics
• Advanced Codex configuration and custom providers

Last checked: 2026-09-23.

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API