Codex runs on Windows in three places: the ChatGPT desktop app, the Codex CLI and the IDE extension. By default the agent runs natively in PowerShell inside a Windows sandbox, with no WSL or virtual machine needed, and you can switch it to WSL2 when your tools and repos live in Linux.
This guide follows OpenAI's Windows docs: the desktop app for Windows, the Windows sandbox and WSL pages, read on 26 October 2026.
How can you run Codex on Windows?
Pick the surface first, then where the agent runs.
| Surface | Native Windows agent | WSL2 agent |
|---|---|---|
| ChatGPT desktop app | Default; commands run in PowerShell | Switch the agent to WSL in Settings and restart |
| Codex CLI | Install from PowerShell | Install the Linux build inside your WSL shell |
| IDE extension (VS Code and forks) | Default | Turn on chatgpt.runCodexInWindowsSubsystemForLinux, or open the folder in a WSL remote window |
The Windows app supports the core workflows, which OpenAI lists as "worktrees, scheduled tasks, Git functionality, the built-in browser, file previews, plugins, and skills." In the app, Codex sits next to Chat and Work; press Alt+3 to switch to it.
How do you install Codex on Windows?
The desktop app. Download the ChatGPT desktop app for Windows from the Microsoft Store link in OpenAI's docs, or install it from a terminal:
winget install --id 9PLM9XGG6VKS -s msstore
Sign in, choose Codex, and open a project folder with Ctrl+O. The Codex app guide covers the rest of the app.
The CLI. OpenAI's Codex CLI page says to start the standalone installer "from a new PowerShell window." The command, also listed in the Codex README, is:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
If you already use Node.js, npm install -g @openai/codex also works. Then run codex in a project folder and choose Sign in with ChatGPT. The Codex CLI guide covers first steps and flags.
The IDE extension. Install it from your editor's marketplace as on any other OS; see the Codex IDE extension guide. On Windows, its chatgpt.runCodexInWindowsSubsystemForLinux setting runs Codex in WSL when WSL is available. Changing it reloads VS Code.
Which Windows versions does Codex support?
OpenAI publishes this support matrix on its Windows sandbox page:
| Windows version | Support level | Notes |
|---|---|---|
| Windows 11 | Recommended | The best baseline, and the one to standardize on for enterprise rollouts |
| Recent, fully updated Windows 10 | Best effort | Version 1809 or newer, for modern console support including ConPTY |
| Older Windows 10 builds | Not recommended | More likely to miss ConPTY and fail in enterprise setups |
OpenAI also expects winget to be available. If it's missing, update Windows or install the Windows Package Manager before you set up Codex.
How does the Codex sandbox work on Windows?
When the agent runs natively, Codex enforces your filesystem and network permissions with a Windows sandbox, for every command and its child processes. There are three implementations:
| Sandbox | When it's used | Trade-offs |
|---|---|---|
mxc |
Recommended on compatible devices | Native process isolation; no admin setup, extra Windows accounts or firewall rules |
elevated |
Preferred fallback when MXC is unavailable | Needs administrator-approved setup; commands still run without admin rights |
unelevated |
Fallback when elevated setup is blocked and policy allows it | Weaker network isolation; no denied read paths |
MXC needs Microsoft Execution Containers support, which OpenAI says Microsoft introduced in Windows 11 24H2 (build 26100.9278) and 25H2 (build 26200.9278). The desktop app prefers MXC automatically for consumer accounts when the device supports it. For the standalone CLI, turn it on in config.toml:
[features]
prefer_mxc = true
[windows]
sandbox = "elevated" # fallback when MXC isn't available
In CLI 0.162.0 and later, you can test MXC for one command without changing your saved setting:
codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
$LASTEXITCODE
You should see MXC_OK and exit code 0. In the desktop app, select Ask for approval below the composer to apply sandbox protections, whether the agent runs natively or in WSL2. OpenAI warns that full access means Codex "is not limited to your project directory and might perform unintentional destructive actions that can lead to data loss." The Codex sandbox and approvals guide explains the modes on every OS.
Should you use native Windows or WSL2?
OpenAI's advice is direct: "Use the native Windows sandbox by default." Choose WSL2 when you need Linux-native tooling, your repos and workflow already live in WSL2, or the native sandbox options don't meet your needs.
| Native Windows | WSL2 | |
|---|---|---|
| Shell the agent uses | PowerShell | Your Linux shell |
| Sandbox | Windows sandbox (mxc, elevated or unelevated) |
Linux sandbox with bubblewrap |
| Best place for repos | Windows drive, reached from WSL at /mnt/<drive>/... if needed |
Linux home folder, such as ~/code/my-app |
| Codex home folder | %USERPROFILE%\.codex |
~/.codex in Linux unless you change it |
File location matters in both directions. If you keep the native agent, OpenAI says storing projects on the Windows filesystem is "more reliable than opening projects directly from the WSL filesystem." If the agent runs in WSL2, keep repos under your Linux home folder, because /mnt/c/... paths can be slower and cause symlink and permission issues.
How do you run Codex in WSL2?
For the CLI, install WSL from an elevated PowerShell, then install Codex inside it:
wsl --install
wsl
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
The Linux sandbox needs bubblewrap. OpenAI's sandboxing docs say to install it with your package manager first, for example sudo apt install bubblewrap on Ubuntu or Debian.
For the desktop app, open Settings, switch the agent from Windows native to WSL, and restart the app; the change doesn't apply until you restart. The integrated terminal is set separately, so you can keep the agent in WSL and still use PowerShell, Command Prompt or Git Bash in the terminal.
For VS Code, run code . from your WSL shell to open a WSL remote window. Look for WSL: <distro> in the status bar, and check that terminals show /home/... paths, not C:\.
One catch: the CLI in WSL doesn't share config, sign-in or session history with the Windows app by default. To share them, point WSL at the Windows Codex home:
export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex
Add that line to ~/.bashrc or ~/.zshrc to keep it. The Codex environment variables guide covers CODEX_HOME in more detail.
How do you fix common Codex problems on Windows?
These fixes come from OpenAI's Windows, sandbox and WSL troubleshooting sections:
| Problem | Fix |
|---|---|
npm.ps1 cannot be loaded because running scripts is disabled |
Set the execution policy, for example Set-ExecutionPolicy -ExecutionPolicy RemoteSigned, after reading Microsoft's guide |
| Git features unavailable in the app | Install Git natively: winget install Git.Git |
Git not detected for a project opened from \\wsl$ |
Store the project on a Windows drive and reach it from WSL through /mnt/<drive>/... |
| Codex needs to run commands as administrator | Start the desktop app with Run as administrator; the agent inherits that level |
| Elevated sandbox setup failed | Approve the admin prompt and retry; on a managed laptop, ask IT about local user, firewall and logon-rights policies; use unelevated meanwhile if policy allows |
Windows error 1385 |
Windows policy is denying the logon type the sandbox users need; ask IT, or use unelevated while it's investigated |
Warning that folders are writable by Everyone |
Remove Everyone write access from the listed folders, then restart Codex or rerun sandbox setup |
| Sandbox stopped working after a change | Restart Codex, rerun the MXC probe or elevated setup, then collect CODEX_HOME/.sandbox/sandbox.log |
| IDE extension installed but unresponsive | Install Visual Studio Build Tools (C++ workload) and the Visual C++ Redistributable (x64), then fully restart VS Code |
| Large repos are slow in WSL | Move the repo out of /mnt/c into ~/code, then run wsl --update and wsl --shutdown |
VS Code in WSL can't find codex |
Run which codex inside WSL and reinstall there if it's missing |
When you send diagnostics to OpenAI, include sandbox.log, your sandbox implementation, the error and your Windows build. Never send the contents of CODEX_HOME/.sandbox-secrets/. In the CLI, /status and /debug-config show the active permissions and config layers when a command can't read a folder.
What else should you set up on Windows?
OpenAI suggests installing a few tools that Codex works better with: Git (which powers the app's review panel), Node.js, Python, the .NET SDK for native Windows apps, and GitHub CLI. You can paste the winget commands from the Windows app docs into the integrated terminal, or ask Codex to install them. After GitHub CLI is installed, run gh auth login to turn on GitHub features.
A few more Windows details worth knowing:
- In the CLI, paste an image with Ctrl+V, or Ctrl+Alt+V when Codex runs inside WSL. See the Codex keyboard shortcuts guide.
- In the desktop app, you can choose a default editor for Open (such as Visual Studio or VS Code) and a default terminal: PowerShell, Command Prompt, Git Bash or WSL.
- IT teams can deploy the app and CLI with Intune, SCCM or other tools; OpenAI's Windows deployment guide has the steps.
If you split work between Windows and WSL, keeping skills in one place saves copying folders between two home directories. Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own, and npx skills add https://github.com/<you>/<repo>.git --all -g installs every skill into Codex on whichever side you run it. Using Claude Code too? The Claude Code on Windows guide covers its setup.