# Install Codex: CLI, desktop app, and IDE extension URL: https://developertoolkit.ai/en/codex/quick-start/installation/ Description: Install the Codex CLI, desktop app, and IDE extension on macOS, Linux, or Windows, then prove the setup works with codex doctor and a read-only smoke test. 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: ```bash 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 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): ```bash 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: ```bash 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). ```bash 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: ```bash 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](/en/codex/quick-start/authentication/) covers plans, API billing, and headless machines. 3. Confirm the sign-in stuck: ```bash 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: ```bash 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: ```bash 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](/en/codex/quick-start/configuration/) 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](/en/ecosystem/models/). **Copy-paste prompt: first-session repository check** ```text 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** ```text 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: ```bash 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](https://chatgpt.com/codex?app-landing-page=true) 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](/en/codex/build/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** ```text 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.]` tables in `config.toml`, managed with `codex mcp` | | Profiles | `$CODEX_HOME/.config.toml`, layered with `codex --profile ` | | 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](/en/codex/quick-start/configuration/) covers `config.toml` keys and permission profiles, and [AGENTS.md for Codex](/en/codex/quick-start/agents-md/) 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. ```bash #!/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](/en/workflows/harness/permissions-and-sandboxing/) 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](/en/codex/quick-start/error-recovery/). ## Where to go next after installing Codex - [Set up Codex authentication](/en/codex/quick-start/authentication/) — ChatGPT plan sign-in, API key billing, headless machines, and credential storage. - [Configure Codex](/en/codex/quick-start/configuration/) — config.toml, profiles, permission profiles, and the defaults worth changing on day one. - [Run your first Codex task](/en/codex/quick-start/first-task/) — A first real change, from prompt to reviewed diff. Setting up another agent as well? See [Claude Code installation](/en/claude-code/quick-start/installation/) and [Cursor installation and setup](/en/cursor-ide/quick-start/installation-setup/).