Install Codex: CLI, desktop app, and IDE extension

Installing Codex means installing the open-source Codex CLI first (standalone script, npm, or Homebrew), then adding the desktop app on macOS or Windows and the IDE extension for VS Code and its forks as needed. The local clients share one CODEX_HOME directory (~/.codex/ by default), so sign-in, config.toml, and MCP servers carry over. codex doctor checks the result.

This page is for the developer setting up Codex on a work machine, and for the tech lead who has to make that setup repeatable across a team. The usual story: someone installed Codex through npm last spring, someone else through Homebrew, a third person only has the desktop app, and nobody can say which version is running or why the IDE panel will not sign in. A deliberate, checked setup is cheaper than debugging mismatched installs later.

What a verified Codex install gives you

• One Codex CLI on your PATH, installed by a method that codex update can detect and upgrade.
• A signed-in session that codex login status confirms, stored where you chose.
• A codex doctor report you can keep as evidence that installation, config, auth, and runtime are healthy.
• A read-only smoke test whose output you can check against your repository in under a minute.
• The desktop app and IDE extension reading the same ~/.codex/ configuration as the CLI.
• A setup-check script a tech lead can hand to every new team member.

Which Codex surface should you install first?

Install the CLI first, even if you plan to live in the desktop app or the editor. The CLI carries the diagnostic commands (codex doctor, codex login status, codex update), and on macOS and Windows codex app launches the desktop app or opens its installer if it is missing.

Surface	Runs on	Install it when	Notes
Codex CLI	macOS, Linux, Windows	Always, first	Terminal UI plus codex exec for scripts and CI
Desktop app	macOS, Windows	You prefer a graphical client to the terminal	Launch with codex app; there is no Linux build
IDE extension	VS Code and forks such as Cursor	You want Codex beside your editor	Shares ~/.codex/ with the CLI
JetBrains, Xcode	Their own IDEs	Your team works in those IDEs	Configured inside the IDE, not through the VS Code extension

Install the Codex CLI

The CLI is a native binary built in Rust. The standalone installer is OpenAI’s first-listed method and needs no Node.js. OpenAI’s install notes list the supported systems as macOS 12+, Ubuntu 20.04+ or Debian 10+, and Windows 11 via WSL2, with 4 GB of RAM as the minimum and 8 GB recommended. The README also ships a native Windows installer (install.ps1); the requirements table in docs/install.md still lists Windows only via WSL2.

macOS / Linux

Run in your terminal:

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

Upgrade later with codex update, which re-runs the same installer.

Windows

Run in PowerShell:

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

For Linux-native toolchains, install inside WSL2 with the macOS / Linux command instead. Pick one of the two per machine, so that the terminal and the editor agree on which codex runs.

npm

Needs Node.js 16 or newer (the package’s engines field on npm, version 0.157.1):

npm install -g @openai/codex

Upgrade later with codex update, which runs npm install -g @openai/codex for you.

Homebrew

Codex is a Homebrew cask, not a formula:

brew install --cask codex

Upgrade later with codex update, which runs brew upgrade --cask codex.

One install method per machine

Two installs (for example, an old npm global and a new standalone binary) leave two codex executables on your PATH. The one that wins depends on PATH order, so the terminal and the IDE can run different versions. Run which -a codex and remove every copy except the one you intend to keep.

Sign in and prove the install works

A version number proves only that a binary exists. The checks below prove that the binary signs in, reads your config, and can run an agent turn against a real repository without changing it.

1. Confirm the binary and its version. On 2026-10-12 the current release is codex-cli 0.162.1 (npm latest, published 2026-10-09).

   codex --version

2. Sign in. Run codex and choose Sign in with ChatGPT (Plus, Pro, Business, Edu, or Enterprise plans include Codex), or pipe an API key from an environment variable:

   printenv OPENAI_API_KEY | codex login --with-api-key

   On a machine without a browser, codex login --device-auth starts a device-code sign-in instead. The authentication guide covers plans, API billing, and headless machines.

3. Confirm the sign-in stuck:

   codex login status

4. Run the built-in diagnosis. codex doctor checks the installation, config, auth, and runtime health; --summary prints only grouped rows and the final count:

   codex doctor --summary

   Save the redacted, machine-readable version when you need evidence for a support ticket or an onboarding checklist: codex doctor --json > codex-doctor.json.

5. From the root of a Git repository, run a read-only smoke test. --sandbox read-only stops the agent from writing files, so the test is safe on any repository:

   codex exec --sandbox read-only "List the commands this repository uses to install dependencies, run tests, and lint. Cite the file each one comes from."

   Open the file the answer cites and compare. If the commands match, the model call, the sandbox, and the repository access all work.

   --sandbox is the legacy control; OpenAI now prefers permission profiles (beta, CLI 0.138.0 or newer), for example -c default_permissions=":read-only". Use one or the other, since the two systems do not compose. The configuration guide covers profiles.

After sign-in, Codex uses its bundled default model, which is GPT-6.1 Sol since CLI 0.159.1 (2026-09-29); GPT-6 Astra was the default from CLI 0.153.4 (2026-09-04) until then. A copy older than 0.153.0 cannot use GPT-6 Astra or GPT-6.1 Sol, which is one more reason to run codex update before you start. Model choice and prices live on the models hub.

Copy-paste prompt: first-session repository check

Do not edit source files; build caches and test artefacts are fine.
Read this repository and report, as a table:
the command to install dependencies, run the unit tests, run the linter,
and run the type checker. For each one give the exact command, the file
and line where you found it, and whether you actually ran it. Run only
the test and lint commands, and report their exit codes. If a command is
missing or ambiguous, write "not found" instead of guessing.

The prompt asks for file and line citations and exit codes, so you verify the answer by checking a handful of cited lines, not by reading everything Codex read. A made-up command has no line to cite. A failing exit code on a clean checkout tells you the machine is missing a toolchain before the agent starts real work.

Copy-paste prompt: machine readiness report for Codex work

Check whether this machine is ready for agent work on this repository.
Without installing anything or changing files, run: git --version,
git status --short, and the runtime version command this project needs
(for example node --version or python3 --version). Compare each version
with what the repository declares (engines field, .nvmrc, .node-version,
.python-version, or pyproject.toml). Output a table with the columns
check, expected, found, and ok/not-ok, then one line on what to fix first.

Install the Codex desktop app on macOS or Windows

The desktop app is a graphical client for the same agent, and the CLI’s /app slash command continues the current terminal session in it. With the CLI installed, the shortest path to the app is one command:

codex app

codex app launches the desktop app and opens the installer if the app is missing. Without the CLI, start from the Codex App page that OpenAI’s README links to. Sign in with the same ChatGPT account you used in the CLI.

The desktop app now ships inside the ChatGPT desktop app as a Codex mode beside Chat and Work, a change dated 2026-07-09 by Neowin (secondary source). On macOS the CLI recognises either ChatGPT.app or Codex.app, so an older standalone Codex install still works with codex app.

The desktop app has no Linux build: the Linux CLI has no app subcommand (checked against codex-cli 0.157.1). On Linux, use the CLI and the IDE extension. Once the app runs, Codex desktop app mastery covers threads, worktrees, and review.

Install the Codex IDE extension

OpenAI’s README lists VS Code, Cursor, and Windsurf as the editors the extension supports (Windsurf was renamed Devin Desktop in June 2026, according to Creeta, a secondary source). Install it from the editor’s extension panel: search for Codex and pick the extension published by OpenAI. Then click the Codex icon in the activity bar and sign in.

VS Code

Open Extensions, search for Codex, and install the OpenAI extension. To keep the file explorer on the left, drag the Codex icon to the secondary side bar on the right.

Cursor

Install from Cursor’s extension panel the same way. Cursor’s activity bar is horizontal by default, so the Codex icon can land in the overflow menu. To move the panel, set the activity bar orientation to vertical in the workbench settings, drag the icon, and switch the orientation back.

JetBrains and Xcode

These IDEs do not run the VS Code extension. According to Neowin (secondary source), JetBrains IDEs from 2025.3 and Xcode 26.3 ship their own Codex integrations, configured inside the IDE. They keep their own settings, so your ~/.codex/config.toml does not apply there.

In the CLI, the /ide slash command pulls your current selection, open files, and other context from the IDE, which is how the terminal and editor sessions share what you are looking at.

Copy-paste prompt: prove the extension sees your editor

Using only my current selection and the files I have open, explain in
three sentences what the selected function does. Then name the test file
that covers it, with the test name. If no test covers it, say "no test
found" and list the files you searched.

Select a function you know well before you send it. A correct summary proves the extension reads your editor context; the “no test found” branch tells you whether the answer rests on evidence or on a guess.

What the local Codex clients share

The CLI, the desktop app, and the IDE extension read the same Codex home directory. It defaults to ~/.codex/; set CODEX_HOME to move it, and set it the same way for every client or they stop sharing.

Shared resource	Where it lives
User config	~/.codex/config.toml
Sign-in	~/.codex/auth.json by default; set cli_auth_credentials_store to keyring or auto to use the OS keyring
MCP servers	[mcp_servers.<name>] tables in config.toml, managed with codex mcp
Profiles	$CODEX_HOME/<name>.config.toml, layered with codex --profile <name>
Instructions	~/.codex/AGENTS.md for you, AGENTS.md in the repository for the project

None of this reaches Codex cloud environments, JetBrains, or Xcode; configure those in their own settings. The configuration guide covers config.toml keys and permission profiles, and AGENTS.md for Codex covers the instruction files.

Make the Codex setup repeatable for a team

A tech lead cannot watch eight people install a tool. Commit a check script instead, and ask for its output in the onboarding ticket. Every command in it is a documented Codex 0.157.1 subcommand, and nothing in it writes to the repository.

#!/usr/bin/env sh
# scripts/check-codex.sh: run from the repository root
set -e
echo "== codex binaries on PATH =="; which -a codex
echo "== version =="; codex --version
echo "== sign-in =="; codex login status
echo "== doctor =="; codex doctor --summary
echo "== read-only smoke test =="
codex exec --sandbox read-only --ephemeral \
  "Name the test command for this repository and the file it comes from. Do not modify files."

The review takes seconds: one path under which -a, the version your team agreed on, a signed-in status, a clean doctor summary, and a smoke-test answer that names the right file. --ephemeral keeps the smoke test out of the saved session history. The permissions and sandboxing guide is the next step once everyone is on the same install.

When Codex installation breaks

codex: command not found after installing. The install directory is not on your PATH in this shell. Open a new terminal first. For Homebrew, run brew list --cask codex to confirm the cask exists. For npm, add the directory that npm prefix -g prints (plus /bin on macOS and Linux) to PATH.

npm fails with EACCES. Do not retry with sudo, which leaves root-owned files that break later upgrades. Use the standalone installer, or set a user-owned npm prefix and install again.

codex update says “Could not detect the Codex installation method”. The binary was installed by hand, for example from a GitHub Release archive. Reinstall with one of the four methods above, then remove the manual copy that which -a codex shows.

The terminal and the IDE show different versions. Two installs are on the machine, or the IDE starts with a different PATH. Run which -a codex, keep one, and restart the editor.

The installer cannot download on a corporate network. The standalone installer downloads from releases.openai.com and falls back to GitHub Releases. To force GitHub Releases, run curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh.

codex app does not exist. You are on Linux, where the CLI has no desktop-app subcommand. Use the CLI or the IDE extension.

Sign-in does not persist. Check whether ~/.codex/auth.json exists. If it does not and you set cli_auth_credentials_store = "keyring", the credential is in the OS keyring, which a headless or SSH session may not reach; switch to auto or file. Then run codex login status again.

Codex ignores the project’s AGENTS.md. Since CLI 0.150.0 (2026-08-26), an untrusted project does not supply its project-level AGENTS.md. Mark the project as trusted when Codex asks on first launch.

The Codex icon is missing in Cursor. It is in the overflow (>>) menu of the horizontal activity bar. Pin it, or switch the bar to vertical as described above.

For errors that show up after installation, while Codex is working, see Codex error recovery.

Where to go next after installing Codex

Set up Codex authentication ChatGPT plan sign-in, API key billing, headless machines, and credential storage.

Configure Codex config.toml, profiles, permission profiles, and the defaults worth changing on day one.

Run your first Codex task A first real change, from prompt to reviewed diff.

Setting up another agent as well? See Claude Code installation and Cursor installation and setup.