Installation and Login (Mac / Windows / Linux)

📚 Series Navigation: The previous article 02 · Core Concepts Overview explained several key terms for Codex (agent, sandbox, approval, local / cloud). This article will guide you through actually installing it on your computer—covering both the Desktop App and CLI lines, explaining login authorization, three-platform differences, and common installation troubleshooting. The next article 04 · Subscription and Pricing will talk about the money part.

In early 2026, OpenAI split Codex into four entries: Web, Desktop App, CLI, and IDE extension. Having used it from CLI all the way to the Desktop App, my most direct observation is—which one to install and how to install it in official terms often doesn't match the old tutorials you search for randomly.

In fact, installing Codex itself is not hard; the hard part is that no one tells you which path is the official right path and which one is an outdated trap. This article will mark the right path for each platform and installation method clearly, so you won't repeat my friend's mistakes.

After reading this article, you will get:

• The installation guides for both Desktop App and CLI across Mac / Windows / Linux (with expected outputs to verify successful installation yourself)
• Comparison of three CLI installation methods (official script / Homebrew / npm), so you know which one to choose
• The difference between the two login methods (ChatGPT account / API key), and the standard solution when login gets stuck in remote/server environments
• A quick lookup table for "error → how to fix," covering most traps beginners run into

---

01 Make Sure of Three Things Before Installing

Don't rush to type commands. Too many people get halfway through only to realize "there is no desktop version for this platform yet" or "this account needs MFA enabled," wasting effort. Confirm these three things first.

First: Which Entry Do You Plan to Use?

Codex has four entries, but in terms of installation, you really have to choose between two paths:

• Desktop App: Graphical interface, click-and-run, suitable for those who don't like touching the terminal. However, it is only available for macOS and Windows; Linux has no desktop App for now (the official site has a Linux waitlist page).
• CLI (Command Line): A programming agent running in the terminal, supported on all three major platforms, and also the most common way for developers.

My recommendation: developers should go straight to the CLI, as it is the most universal and cross-platform without dead ends. This article focuses on the CLI, with a dedicated section for downloading and logging into the Desktop App for the first time. You can start with either—the login state is shared between CLI and IDE extensions (Desktop Apps log in separately, covered in Section 06).

Second: You Must Have a Usable Account

The easiest thing for beginners to overlook: Codex follows the ChatGPT subscription.

The official documentation clarifies that ChatGPT Plus, Pro, Business, Edu, and Enterprise subscriptions all include Codex usage. You can also skip binding a subscription and use OpenAI API keys on a pay-as-you-go basis—but when logging in with an API key, some functions that rely on the ChatGPT workspace will be restricted or unavailable (for example, Cloud Codex strictly requires a ChatGPT login).

Running the local CLI with an API key is fine; OpenAI charges your Platform account based on standard API pricing, which is separate from the quota in your subscription.

Details on accounts and pricing will be expanded in the next article, 04 · Subscription and Pricing. This article assumes you have a working ChatGPT subscription or API key in hand.

Third: Network Access to OpenAI Must Work

Regardless of the entry, Codex must connect to the internet, specifically to OpenAI's servers. Accessing domains like chatgpt.com and platform.openai.com in mainland China usually requires a VPN. You must keep it enabled during installation, login, and when running daily tasks; otherwise, it is extremely easy to get stuck on "download timeout" or "login callback failure." This is the number one source of traps for domestic users, so prepare your proxy first.

💡 Summary in one sentence: Before starting, confirm three things—choose CLI for the entry (universal cross-platform), have a ChatGPT subscription or API key for the account, and ensure stable network access to OpenAI. Cross these three gates before typing commands.

---

02 Path 1: Desktop App (Mac / Windows)

For those who don't like touching the terminal, starting with the Desktop App is the easiest path.

Analogy: The Desktop App is like a "ChatGPT with a project directory." You chat with it just like you do on the ChatGPT web version; the difference is that it can bind to a folder on your computer to read files, modify code, and run commands—essentially stitching the chat box, IDE project directory, and long-term memory together.

Real-world scenarios:

• You are a product manager or designer who doesn't write code but wants the AI to help modify a small requirement or check how a feature is implemented in the project.
• You want to run multiple projects in parallel—having it run tests on project A while you continue listing requirements for project B.
• You want a graphical "review panel" to inspect what it changed line-by-line before deciding whether to accept it.

Download and Installation

Open https://chatgpt.com/codex and download the installation package for your platform:

Platform	What to Choose
macOS (Apple Silicon)	Download the default package directly
macOS (Intel Chip)	Choose Intel build, do not download the wrong one
Windows	Download the official installer
Linux	No Desktop App yet; fill out the form on the official website to wait for notice; use CLI for now

Mac users unsure if they have Intel or Apple Silicon? Click the Apple icon in the top left → "About This Mac." If "Chip" writes Apple M series, it is Apple Silicon; if it writes Intel, download the Intel build. Downloading the wrong chip version will fail to install or crash on startup.

First Login and Project Selection

Once the App is installed, follow these three steps:

1. Login: Log in using your ChatGPT account or OpenAI API key (API key login restricts some features, covered in the next section).
2. Select Project: Choose a folder where you want Codex to work. If you have used the App, CLI, or IDE extension before, your historical projects will be listed here.
3. Send Your First Message: After selecting the project, confirm that the bottom left is set to Local (so Codex works on your machine instead of the cloud), and type your requirement into the input box.

Don't rush to play with complex features when you first enter; focus on "Conversations" and "Projects". Conversations work just like the ChatGPT web version, while Projects bind to a folder on your computer where Codex will do its work.

After installing and opening the App, you can switch languages in the bottom left "Settings → General → Language" (the App can auto-detect it). Note that the right sidebar and bottom bar are expanded via the top-right icons. The interface looks roughly like this:

💡 Summary in one sentence: The Desktop App is only for Mac and Windows; Mac users make sure to distinguish between Intel and Apple Silicon builds. Once installed, it is just three steps: log in, select the project folder, and confirm Local before sending messages.

---

03 Path 2: CLI (One Command for Three Platforms)

First, the conclusion: always prefer the official installation script (standalone installer) for all platforms. It does not depend on Node.js, and runs as a standalone binary, which is the cleanest way.

Analogy: The official script is like a "one-click install" in an app store. Click it, and it downloads and places the binary itself, without digging into other parts of your system. The old npm method is like "installing a package manager first, then using it to install the app"—adding an extra layer of dependency (Node.js) and another place where things can go wrong.

macOS / Linux

Open your terminal and paste this line:

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

Mainland China network tip: chatgpt.com usually requires a VPN to access stably. Keeping a proxy enabled during installation will save you from most "stuck / timeout" errors.

If you are writing automation scripts or installing unattended in CI (where you don't want any interactive prompts), the official CLI provides an environment variable:

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

Windows (Native, No WSL Needed)

Run in PowerShell (the prompt looks like PS C:\>):

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

Unattended version (CI / Script):

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

Here -ExecutionPolicy ByPass temporarily allows script execution for this run and won't permanently modify your system policies. irm (Invoke-RestMethod) fetches the script, and iex (Invoke-Expression) executes it. If you see irm is not recognized, it means you are running in CMD; open a PowerShell window instead.

Other Options: Homebrew / npm

Besides the official script, there are two alternative paths. Here is a comparison to choose from:

Installation Method	Command	Prerequisite	My Advice
Official Script	curl ... | sh (Win uses irm)	None	First Choice, standalone binary, cleanest
Homebrew (Mac)	brew install --cask codex	Homebrew installed	For those who heavily use brew to manage software; updates are slightly behind the official site
npm	npm install -g @openai/codex	Node.js	For those used to globally installing tools with npm

Homebrew updates are a day or two later than the official site due to the review process of the Cask maintenance team; the benefit is that versions have been tested, which is actually more stable for those who don't like chasing the absolute latest version.

Homebrew (macOS):

brew install --cask codex

npm (any platform, requires Node.js first):

npm install -g @openai/codex

A few traps to know in advance:

• Whether to add sudo for npm depends on your Node environment. Many old tutorials write sudo npm install -g, but globally installing npm packages with sudo is notorious for leaving a mess of permission issues. My habit is to use nvm or Volta to install Node in the user directory, avoiding sudo entirely. If you run into permission errors, instead of fighting it with sudo, go straight to the official script path, which completely bypasses npm.
• Homebrew is --cask, not a normal formula; do not miss --cask, and make sure the package name is exactly codex.

💡 Summary in one sentence: For the CLI, blindly choose the official script—use curl ... | sh on Mac/Linux, and irm on Windows. It is a standalone binary that does not depend on Node. Homebrew and npm are fallbacks; try to avoid sudo with npm.

With the two installation paths covered, let's put them side-by-side:

This diagram shows the Desktop App and CLI lines side-by-side: left line downloads the package, opens it, and logs in within the App; right line installs codex and runs codex login. Both paths lead to the same destination—"Successfully logged in and ready for use." For login, you can choose either your ChatGPT account or an API key.

---

04 Windows Users: Native or WSL?

Windows has the most details to watch out for among the three platforms, so it gets a dedicated section.

The official docs list three ways to run it:

• Native Windows + elevated Sandbox: The first choice. Uses a dedicated low-privilege sandbox user, file system boundaries, and firewall rules to lock Codex within the working directory, providing the strongest safety.
• Native Windows + unelevated Sandbox: The fallback. Used when company computer policies do not allow administrator-level configurations like elevated mode; it is weaker than elevated but still offers protection.
• WSL2 (Windows Subsystem for Linux): Runs in a Linux environment using Linux sandboxes. Choose this when you need Linux toolchains or when your repository already lives in WSL2.

Official comparison table:

Method	What Is Needed	When to Use
Native + elevated	Admin-approved sandbox config	Default first choice, best performance and safety
Native + unelevated	No admin-level config required	Fallback when company policies block elevated mode
WSL2	WSL2 enabled	When Linux toolchain is required, or repository already in WSL2

Crucial warnings:

• Windows Version: The official recommendation is Windows 11. Windows 10 is "supported on a best-effort basis," requiring 1809 or newer (relying on modern console components like ConPTY); older Win10 versions are not recommended.
• winget Must Work: If it is missing, update Windows or install the Windows Package Manager first.
• WSL1 Is No Longer Supported: Since Codex 0.115, the Linux sandbox switched to bubblewrap, and WSL1 was dropped after 0.114. If you want to use WSL, use WSL2.

If you go with WSL2, first install the subsystem in an Administrator PowerShell, then enter the WSL shell to run the CLI install script:

wsl --install
wsl

Once inside WSL (the prompt changes to Linux style):

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

A WSL performance trap: do not place your code repository under Windows mount paths like /mnt/c/.... I/O will be significantly slower, and you will easily run into symlink and permission issues. Placing it in the Linux home directory (like ~/code/my-app) is the fastest. If you need to access these files from Windows, type \\wsl$ in File Explorer.

The diagram below helps you make a decision in three steps:

This diagram says: prefer native elevated; fall back to unelevated if blocked by company policies; go with WSL2 if a Linux environment is needed.

💡 Summary in one sentence: Windows prefers native + elevated sandbox, falls back to unelevated if blocked by policies, and uses WSL2 if a Linux environment is needed. Note that WSL1 has been dropped, and Windows 11 is the most stable.

---

05 Verifying Successful Installation

Once the CLI is installed, don't rush to use it; take ten seconds to verify. Open a new terminal window and run:

codex --version

The expected output is a version number (the exact numbers will update over time, which is normal):

codex-cli 0.139.0

Seeing the version number = successful installation. If you get command not found: codex (or 'codex' is not recognized on Windows), do not reinstall yet—it is highly likely that the PATH was not configured correctly (the installation directory is not in the system search paths). Refer to Section 08 for the fix.

The specific version check parameters and "how to manually upgrade to the latest version" are subject to the output of the official documentation or codex --help. The official CLI is constantly adjusting this, so I won't write down a hardcoded command name to avoid misleading you if it becomes outdated. Checking what subcommands are supported in the current version using codex --help after installation is the most reliable way.

The Desktop App version can be found in the App menu. If the App and CLI versions are inconsistent, it may lead to feature differences; check both version numbers when things don't align.

💡 Summary in one sentence: For the CLI, it's successful if codex --version prints a version number; upgrades and version parameters are subject to the official docs and codex --help, so don't blindly follow hardcoded commands in old tutorials.

---

06 Login: Making It Recognize You

The newly installed Codex is an empty shell that doesn't know you; you must log in and bind an account to start working. Launch the CLI in your project directory:

codex

If there is no valid login state, it will guide you to log in with ChatGPT by default, opening a browser window for authorization. Once authorized, the browser returns the access token to the CLI, and you are logged in.

Choosing Between the Two Login Methods

Method	How to Log In	Suitable for	Notes
ChatGPT Account (Recommended)	Select Sign in with ChatGPT, authorize in browser	Most users, and those who need cloud features	Usage counts towards your ChatGPT subscription
API key	Select API key login, retrieve key from OpenAI Developer Platform	CI/CD, programmatic CLI usage	Billed based on standard API pricing; some features relying on ChatGPT workspaces will be unavailable

I use my ChatGPT account for daily development—the subscription quota is plenty, and I can use cloud tasks. I only use API keys when writing automation scripts and putting them into CI, since it doesn't require browser interaction, making it suitable for unattended tasks. However, the official docs warn: do not run Codex with an API key in untrusted or public environments.

Where Login States Are Stored and Expiry

Once logged in, credentials are cached locally and reused next time without logging in again. Two key points:

• The CLI and IDE extensions share the same login cache—logging out in one will require logging back in next time on the other.
• The cache is stored locally in a plain text file ~/.codex/auth.json or in the OS system credential store (Keychain on macOS); you can specify this via cli_auth_credentials_store (file / keyring / auto, see Section 18 for details).

⚠️ ~/.codex/auth.json contains your access token; treat it like a password. Do not commit it to Git, paste it in tickets, or share it in chats.

For sessions logged in via ChatGPT, Codex will automatically refresh the token before it expires, so you rarely need to log in repeatedly during normal use.

What if Remote / Server / WSL Login Gets Stuck?

This is the trap my friend fell into: in remote servers, headless environments, or when local network configurations block localhost callbacks, browser-based login will not work—either because the browser is opened on a different machine or the OAuth callback cannot return. The official preferred solution is Device Code Login.

Select Sign in with Device Code on the interactive login screen, or run directly:

codex login --device-auth

This is a beta feature. It gives you a link and a one-time verification code. You can open the link in any browser that has internet access, type in the code, and log in, completely independent of whether the local machine has a browser.

Device code login must be enabled in your ChatGPT security settings (for personal accounts) or workspace permissions (for admins). If it is not enabled on the server side and device codes do not work, there are two fallbacks:

1. Copy the Authentication Cache: Run codex login on a machine with a browser, verify that ~/.codex/auth.json is generated, and then copy it to the same path on the headless machine. For example, via SSH:

   ssh user@remote 'mkdir -p ~/.codex'
   scp ~/.codex/auth.json user@remote:~/.codex/auth.json

2. SSH Port Forwarding for Callbacks: Forward Codex's local callback port (default localhost:1455) from the remote machine to your local machine, allowing you to run the normal browser flow:

   ssh -L 1455:localhost:1455 user@remote

   Then run codex login in this SSH session, and open the address in your local browser as prompted.

I eventually got my friend to log in using the device code method—a single codex login --device-auth command, copying the link to his own computer's browser, and pasting the code. It was done in thirty seconds, much better than waiting in vain for a browser window to pop up.

💡 Summary in one sentence: Log in using a ChatGPT account by default, with credentials stored in plain text in ~/.codex/auth.json (treat it like a password); remember codex login --device-auth for remote/server environments, and fall back to copying cache or SSH port forwarding for port 1455 if needed.

---

07 Hands-on: Running It for the First Time from Scratch

Installing it is not enough; run it once to confirm the entire loop works. This minimal process does not rely on an existing project; just create a new empty directory.

First, create a test directory, enter it, and launch Codex:

mkdir codex-test && cd codex-test
codex

The first launch will guide you to log in (follow Section 06). Once logged in, you will see the welcome screen and input prompt.

Second, ask it to do something real—use plain English (no need to remember command formats):

Write a function that prints hello world in test.py

Expected behavior: Codex has approval enabled by default—when it needs to modify files or run commands, it will present the actions to you first, waiting for your confirmation (selecting Yes) before actually executing them. This is its core rhythm: present the plan first, wait for your approval, and then execute, rather than modifying your things silently (detailed approval and sandbox modes will be covered in a dedicated article).

Once confirmed, test.py will appear in the directory. Exit the CLI by pressing Ctrl + C or typing /exit (subject to the UI prompt).

Third (a habit strongly recommended to develop), since Codex will modify your codebase, make a Git checkpoint before and after letting it work, so you can roll back with one click if it breaks things:

git init
git add -A && git commit -m "checkpoint before codex works"

By this step, you have successfully run through the entire loop: "install → log in → give instructions → review actions → confirm → file modification." Seeing it stop for the first time, presenting the actions it wants to take for your nod, gives you a real sense of 'this thing can actually work, and it won't act recklessly'. When I first ran through it, I was first amazed by the speed at which it read the project, and then realized it was waiting obediently for my approval.

Let's thread these steps into a single line:

The most critical part of the diagram is the approval split: it only works if you click Yes; clicking No sends you back to explain again—it never modifies your things silently.

💡 Summary in one sentence: You can run through the whole loop by creating a new empty directory—launch codex to log in, give plain instructions, inspect actions and select Yes; making a Git checkpoint before and after is the most stable rhythm to ensure safety.

---

08 Troubleshooting: Common Traps for Beginners

Errors are almost inevitable when installing, but the vast majority have standard solutions. We have organized the most common ones into a quick lookup table—diagnose the cause first, then apply the fix; do not reinstall blindly as soon as an error occurs.

Error / Symptom	Real Cause	How to Fix
command not found: codex	Installation directory is not in PATH	Add installation directory to PATH (see below)
'codex' is not recognized (Windows)	Same as above, PATH not configured / terminal not restarted	Configure PATH and restart terminal
irm is not recognized	Ran a PowerShell command in CMD	Open PowerShell and run the irm command
Browser spins forever during login / callback fails	Remote / headless / local network blocking localhost callback	Use codex login --device-auth (see Section 06)
Installation script gets stuck / times out	Proxy not used for local network	Enable a VPN and retry, or switch to Homebrew
API key login restricts some features	API key login inherently limits some ChatGPT workspace features	Switch to logging in with a ChatGPT account
Windows error 1385 (sandbox command fails)	Windows policy does not grant sandbox users login permissions	Contact IT for company machines; switch to unelevated sandbox for urgent use
codex still runs after uninstallation	Multiple installations of codex conflicting	Run which -a codex to find and delete duplicates

Let's expand on the two most common ones.

Trap 1: command not found: codex (Most Common)

Running codex says command not found—this doesn't mean it wasn't installed, but that the installation directory was not added to the system search paths (PATH).

Analogy: PATH is like a list of registered addresses for the system. Having a program installed is like having a house built, but the system only searches addresses registered on this list. Since the address of codex is not registered, the system doesn't respond when you call it.

Fix (macOS defaults to Zsh; first check which directory the installation script placed codex in, then add that directory to PATH):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

The above assumes the installation directory is ~/.local/bin; your actual directory is subject to the installation script's output (the script usually prints where it placed the binary and whether you need to manually add it to PATH). Linux mostly defaults to Bash, so replace ~/.zshrc with ~/.bashrc. On Windows, add the corresponding installation directory to your user PATH environment variable, then restart the terminal.

Verify after modification:

codex --version

If it prints the version number, it is fixed.

Trap 2: Conflicting Multiple Installations

If you previously installed it via npm and then ran the official script again, multiple codex versions may exist simultaneously, leading to version mismatch, strange behaviors, or even running after uninstallation. First, check how many exist in PATH:

which -a codex

If more than one is listed, keep only the one you want to use (usually the one installed by the official script) and delete the rest. For example, uninstall the global npm installation:

npm uninstall -g @openai/codex

Often running which -a codex reveals that npm and the official script have each installed one, competing for the same command name—deleting the duplicates and cleaning up PATH resolves it instantly. I once fell into this trap myself: I installed it via npm first for fun, and later switched to the official script, but codex --version kept showing the old npm version because the npm directory was placed first in PATH.

💡 Summary in one sentence: Check the table for the cause when an error occurs, do not reinstall by reflex. Missing commands are usually a PATH issue; strange behaviors / incomplete uninstallations are usually multiple installations conflicting—which -a codex will expose them.

---

09 Summary

This article has covered the entire process of getting set up and running:

• Three things to confirm before installing: choose CLI for the entry (universal cross-platform), have a ChatGPT subscription or API key for the account, and ensure stable network access to OpenAI.
• Two installation paths: Desktop App is macOS and Windows only (distinguish between Intel and Apple Silicon builds for Mac); CLI is available on all three platforms, with the official script preferred (curl ... | sh / Windows irm), while Homebrew and npm are fallbacks.
• Windows details: native + elevated sandbox is preferred; falls back to unelevated if blocked by policies; uses WSL2 if a Linux environment is needed. WSL1 has been dropped.
• Login defaults to ChatGPT account, with credentials cached in plain text in ~/.codex/auth.json (treat it like a password); remember codex login --device-auth for remote/server environments.
• Diagnose errors first: check PATH for missing commands, and check multiple installations for strange behaviors.

You should now be able to install Codex (App or CLI) independently on your machine, log in, run the first example, and troubleshoot common installation errors.

The next article 04 · Subscription and Pricing will talk about the money part: how much Codex quota does each ChatGPT subscription tier provide? How is the API key pay-as-you-go billed? Which is more cost-effective compared to Claude Code? Now that you have installed it and are ready to run, get the quota and pricing straight first to avoid being blocked by limits in the middle of a task.

A question to leave you with: did you choose a ChatGPT account or an API key when logging in? The difference is more than just the "login method"—pricing and available features differ too, which is exactly the entry point for the next article.

---

Installing it only gives you the tool; understand the quota and billing first to use it freely—see you in the next article.

---

Recommended Reading

• Rules and Hooks (Rules & Hooks): Adding checkpoints and triggers to Codex
• Windows Usage Guide: Native or WSL, how to run without headache
• Agent Skills: Packaging a set of tasks to teach Codex how to handle them