Installation

Installing Codex means setting up three local surfaces: the ChatGPT desktop app with Codex mode on macOS or Windows, the open-source CLI available through a standalone installer, npm, or Homebrew, and an IDE extension for VS Code and compatible forks, with JetBrains and Xcode offering separate integrations. All three local clients share the same ~/.codex/ configuration directory, so authentication and settings carry over between them once CODEX_HOME matches.

You have a ChatGPT plan that includes Codex, and now you are staring at the downloads page wondering which client to install first. The local clients share Codex authentication and configuration once set up.

What Installing Codex Gets You

• The ChatGPT desktop app with Codex mode installed on macOS or Windows
• The Codex CLI available globally via codex command
• The Codex IDE extension running in VS Code, Cursor, or Windsurf, with separate JetBrains and Xcode options understood
• All three surfaces sharing the same ~/.codex/ configuration directory
• Verification that each surface launches and authenticates correctly

Install ChatGPT Codex on Desktop (macOS or Windows)

Codex is now a mode in the new ChatGPT desktop app for macOS and Windows. It provides parallel threads, worktree isolation, built-in Git tools, automations, and an integrated terminal. If you already use the standalone Codex app, update it normally: it becomes the new ChatGPT app and preserves existing Codex tasks and projects. See OpenAI’s migration guide.

macOS

1. Open the official ChatGPT download page and choose macOS. The page serves the appropriate current build.

2. Open the installer and add ChatGPT to your Applications folder.

3. Launch ChatGPT from Applications. macOS may ask you to confirm opening an app from an identified developer — click Open.

4. Sign in with your ChatGPT account when prompted.

5. Select Codex in the mode switcher, then open a project folder.

Windows

1. Open the official ChatGPT download page and choose Windows to continue to the current Microsoft Store installer.

2. Launch ChatGPT from the Start menu after the install finishes.

3. Sign in with ChatGPT, select Codex in the mode switcher, and open a project folder.

Caution

The ChatGPT desktop app with Codex mode is available on macOS and Windows. On Linux, use the Codex CLI or IDE extension below.

Tip

Prompt to verify the App is working:

After selecting Codex mode and a project, type this into the desktop thread:

Tell me about this project

Codex should read your project structure and give you a summary. If it does, the App is fully operational.

Install the Codex CLI

The CLI is open-source, built in Rust, and runs on macOS, Linux, and Windows. The standalone installer is the primary path and does not require Node.js.

macOS / Linux

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

The installer adds the current standalone build to your user PATH. Re-run it to update, or use codex update from a current installation.

Windows PowerShell

irm https://chatgpt.com/codex/install.ps1 | iex

For Linux-native toolchains on Windows, you can instead run the macOS/Linux installer inside WSL2.

npm

npm install -g @openai/codex

Verify the installation:

codex --version

Upgrade to the latest version later with:

npm install -g @openai/codex@latest

The npm package is an optional wrapper and requires Node.js 16 or newer.

Homebrew

brew install codex

Verify the installation:

codex --version

Upgrade later with:

brew upgrade codex

After installing, run codex --version (the current release covered here is 0.144.1), then run codex. The first launch prompts you to sign in with ChatGPT or an API key.

Note

The CLI is available on macOS, Linux, and Windows. For the best Windows experience, run Codex inside a WSL workspace and follow the Windows setup guide.

Tip

Prompt to verify the CLI is working:

Navigate to a project directory and run:

codex "What files are in this project?"

If Codex lists your files, authentication and sandboxing are both working.

Install the IDE Extension

The OpenAI Codex extension targets VS Code and compatible forks such as Cursor and Windsurf. JetBrains and Xcode provide their own separate Codex integrations; they are not builds of the VS Code extension.

VS Code

Install from the Visual Studio Code Marketplace or open VS Code and search for “Codex” in the Extensions panel.

After installation, the Codex icon appears in your left sidebar. Click it, sign in, and you are ready.

Cursor

Install the extension by searching for “Codex” in Cursor’s extension panel or use cursor:extension/openai.chatgpt.

The activity bar in Cursor displays horizontally by default, which can hide the Codex icon. If you do not see it, look for collapsed items or pin the Codex extension in the bar.

Windsurf

Search for “Codex” in Windsurf’s extension panel or use windsurf:extension/openai.chatgpt.

JetBrains

For IntelliJ, PyCharm, WebStorm, Rider, and other JetBrains IDEs (2025.3+), update the JetBrains AI Assistant plugin and choose Codex in JetBrains AI Chat. This native JetBrains integration supports ChatGPT login, API keys, and JetBrains AI subscriptions.

Xcode

Xcode 26.3+ exposes Codex through Xcode’s own agentic coding integration. Configure it inside Xcode rather than installing the VS Code extension; see Apple’s Xcode 26.3 announcement.

Moving Codex to the Right Sidebar

Most developers prefer the Codex panel on the right side of their editor, keeping the file explorer on the left.

In VS Code, simply drag the Codex icon from the left sidebar to the right. In Cursor, you may need to temporarily set the activity bar orientation to vertical in Workbench settings, restart, drag the icon, then reset to horizontal.

Tip

Prompt to verify the IDE extension is working:

Open the Codex sidebar panel and type:

Tell me about this project

Codex should read your open workspace and summarize it.

How the Surfaces Connect

The OpenAI local clients (ChatGPT desktop, CLI, and VS Code-family extension) can share configuration and cached credentials when they use the same CODEX_HOME:

Shared resource	Location
User config	~/.codex/config.toml
Authentication	~/.codex/auth.json or OS keyring
MCP servers	Defined in config.toml, shared by all surfaces
AGENTS.md	Read from ~/.codex/AGENTS.md (global) and project root (project-level)

This means you can configure local OpenAI clients once. It does not copy local settings into Codex Cloud environments, JetBrains AI, or Xcode; configure those surfaces in their own UI or workspace settings.

Codex mode in the ChatGPT desktop app and the IDE extension also sync when both are open in the same project. The desktop app tracks which files you view in your editor (Auto Context), and threads started in one surface appear in the other.

When Codex Installation Breaks

App does not open on macOS: Download the current ChatGPT build again from chatgpt.com/download rather than relying on an old Codex DMG filename. Check System Settings > Privacy & Security if macOS blocks the app.

CLI install fails with npm: Make sure Node.js 16+ is installed (node --version). If you get EACCES errors, use the standalone installer or configure a user-owned npm prefix instead of sudo.

IDE extension not visible: In Cursor, the extension may be hidden in the collapsed section of the horizontal activity bar. Look for a >> overflow menu in the bar, or switch to vertical orientation temporarily.

Authentication does not persist: Check that ~/.codex/auth.json exists after signing in. If it is missing, your OS credential store may be in use. See the authentication guide for credential storage configuration.

“codex: command not found” after Homebrew install: Run brew link codex or ensure /opt/homebrew/bin is in your PATH.

Where to Go Next After Installation

Set Up Authentication Configure ChatGPT subscription access or API key billing