Codex CLI on Windows: Step-by-Step Install Guide

👁 143 reads

You can install Codex CLI on Windows 11 with a single PowerShell command: using the official installer, npm, or winget. WSL is no longer required because Codex has its own Windows sandbox. Below is the complete path from installation to your first task, with commands we tested on our machine on October 3, 2026. Full details on the agent, pricing, and models are in our Codex from OpenAI guide.

Requirements: Node, PowerShell or WSL

The most common question is: do you need WSL on Windows. OpenAI’s documentation as of October 3, 2026 is clear: use the native Windows sandbox by default, and only choose WSL2 if you need Linux tools or your entire project already lives in WSL. Watch out for the old docs/install.md file in the GitHub repository, which still says “Windows 11 via WSL2” - that’s an outdated table, superseded by the newer Windows sandbox page.

• System: 64-bit Windows (the installer stops on 32-bit), preferably Windows 11. Windows 10 needs the ConPTY console mechanism, meaning version 1809 or newer.
• winget should be available on your system - the documentation lists it as a prerequisite.
• Node.js only for npm installation. The package requires node >=16 (engines field in package.json). The PowerShell installer and winget don’t need Node.
• RAM: according to the repository, minimum 4 GB, recommended 8 GB. Git is not mandatory but useful.

We checked what actually lands on disk when installing via npm. Node is just a starter: the codex.js file launches a native program written in Rust. The entire package takes 430 MB, of which codex.exe alone is 327 MB. Alongside it are rg.exe (ripgrep for searching code), codex-windows-sandbox-setup.exe, and codex-command-runner.exe, among others.

Step-by-Step Installation

You have three official routes. Choose one, because two parallel installations are the most common source of PATH confusion.

We reviewed the PowerShell installer content (worth doing with any irm ... | iex script). It shows that:

• it adds the codex.exe directory to the user PATH, so open a new PowerShell window after installation;
• it checks the SHA256 hash of the downloaded archive;
• it detects a previous npm installation and offers to remove it, warning that with two installations “which one runs is determined by PATH order”.

After installation, check what you have. Results from our machine:

1. codex --version returns codex-cli 0.160.0 (we checked).
2. where codex shows two files: C:Users...AppDataRoamingnpmcodex and codex.cmd (we checked). In the same npm directory, it also creates codex.ps1 - this is what causes ExecutionPolicy trouble, discussed below.
3. node --version returns v26.10.0 on our machine (we checked).

Login: ChatGPT Account or API Key

Type codex login (or simply codex in a project directory). A browser opens, you log into ChatGPT, and the credentials return to the terminal. Check status with codex login status - on our machine it returns Logged in using ChatGPT (we checked).

• ChatGPT account - you consume your plan limit, cloud features work. Codex in CLI is available from the Plus plan; Free and Go only get GPT-6 Luna in the desktop app. We described the real limit amounts in our Codex limits in Plus article.
• API key - you pay for tokens according to API pricing, you lose the cloud and automatic GitHub reviews. In PowerShell: $env:OPENAI_API_KEY | codex login --with-api-key (documentation gives the printenv version for Linux and macOS).
• Without browser (server, remote machine) - in codex login --help there’s a --device-auth flag, meaning device code login (we checked the flag exists; no description in help).

Login data goes to the %USERPROFILE%.codex directory (on our machine, the auth.json file). Don’t put this directory in a repository or cloud sync.

First Run and AGENTS.md

1. Make a commit in your repository so you have a restore point.
2. In the project directory, type codex and give it a low-risk task, like “Describe the structure of this project”.
3. Type /init - Codex will generate a skeleton AGENTS.md file with instructions for the agent.
4. Save permanent rules for all projects in %USERPROFILE%.codexAGENTS.md.

Codex reads the global AGENTS.md first, then files from the repository root down to the current folder. The combined limit is 32 KiB (project_doc_max_bytes setting), so long documents get truncated anyway. Full description of session work, with models and commands, is in our Codex hub.

Approval Modes and Sandbox

Two things work together: the sandbox determines what the agent can access, and the approval policy says when it asks. In a session, you set this with the /permissions command, at startup with flags. Values below are from codex --help in version 0.160.0 (we checked):

The default mode from documentation, “Ask for approval”, is workspace-write plus on-request: the agent edits files in the project and runs normal commands, but asks before going online or outside the directory. On Windows, the sandbox has two variants, selected in config.toml:

• [windows] sandbox = "elevated" - recommended, creates separate lower-privilege users and firewall rules, requires administrator consent (UAC) during setup. Our config.toml has this variant (we checked the file).
• sandbox = "unelevated" - fallback, works on your user’s restricted token and ACL permissions, weaker network isolation. Useful on a corporate laptop where policy blocks user creation.

We don’t give the agent full access in directories with client data - more in our code agent in the enterprise article.

Updates

• any installation: codex update (subcommand “Update Codex to the latest version” in codex --help, we checked);
• npm: npm install -g @openai/codex@latest;
• winget: winget upgrade --id OpenAI.Codex;
• PowerShell installer: run the same script again, according to documentation.

Alpha versions are also on npm: on the morning of October 3, 0.162.0-alpha.10 was published (we checked in npm view). Regular @latest doesn’t install them. Installation problems are diagnosed by codex doctor.

Common Windows Errors and Solutions

• “codex is not recognized” - terminal doesn’t see the new PATH. Open a new window. With npm, check if %APPDATA%npm is in PATH (npm config get prefix shows the directory). where codex tells you which file is running.
• “running scripts is disabled on this system” - PowerShell hits codex.ps1 from npm, and execution policy is Restricted. Solutions: run codex.cmd, use cmd, or change policy for yourself only: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. The official installer bypasses the problem with -ExecutionPolicy ByPass for one process only.
• Two versions at once - codex --version shows old version after update. Usually you have npm and installer simultaneously. Keep one installation.
• Sandbox setup failed - rejected UAC, blocked user creation or firewall rules. According to documentation: retry with administrator consent, and if the company blocks it, temporarily switch to unelevated.
• Error 1385 - Windows denies sandbox users logon rights. This is an IT department matter; until then, use unelevated.
• Sandbox can’t read directory - in session: /sandbox-add-read-dir C:fullpath. Access works until end of session.
• Paths too long - Codex doesn’t describe this, but Git on Windows with deep node_modules reports “Filename too long”. git config --global core.longpaths true helps, and in the system enabling long paths (LongPathsEnabled) by administrator.
• Antivirus - documentation is silent about it, we had no blocking. If corporate antivirus removes codex.exe or codex-windows-sandbox-setup.exe, don’t disable protection, ask the administrator for an exception for the installation directory.
• Corrupted config.toml after crash - this actually happened to us: after a blue screen on September 9, 2026, our config.toml was 73,334 bytes and all were zeros. Keep a backup of this file, because without it you’re recreating settings from memory.
• Slow in WSL - don’t work on /mnt/c/.... OpenAI advises keeping the repository in the Linux home directory, e.g. ~/code.

Uninstallation

1. If you used a ChatGPT account, first codex logout.
2. npm: npm uninstall -g @openai/codex; winget: winget uninstall --id OpenAI.Codex.
3. PowerShell installer: we found no official uninstall command. The script shows files are in %LOCALAPPDATA%ProgramsOpenAICodex and %USERPROFILE%.codexpackagesstandalone, and the entry is in user PATH.
4. Delete the %USERPROFILE%.codex directory with settings, session history, and AGENTS.md only if you won’t return to Codex. The ChatGPT desktop app also uses it.

Comparison with a competitor is in our Codex or Claude Code article, and we describe the version that works without your computer in Codex in the cloud.

Google · Your sourcesQuantslant higher in your Google - one clickAdd to preferred sources →

Sources and Verification Date

• OpenAI: Windows sandbox (Windows versions, elevated and unelevated modes, errors)
• OpenAI: Codex in WSL (WSL1 through version 0.114)
• OpenAI: Codex CLI documentation
• OpenAI: login and permission modes
• OpenAI: AGENTS.md
• GitHub: openai/codex (README, installer, RAM requirements)
• npm: @openai/codex and winget manifest OpenAI.Codex

Commands marked “we checked” were run on October 3, 2026 on Windows 11 with Codex CLI 0.160.0 installed via npm. Remaining steps are described according to OpenAI documentation and the installation script content.