Guide
Codex on Windows: PowerShell or WSL, and what breaks in each
Published · Updated
Short answer: Run Codex natively in PowerShell if your project and tools live on Windows. OpenAI's docs make the native Windows sandbox the default [2]. Run it in WSL2 if you need Linux tooling or your repos already live in WSL, and keep the repo in your Linux home directory, not under /mnt/c [4].
Checked on 18 November 2026. The latest Codex CLI release on GitHub was 0.170.0 [17].
Where Windows support stands
The Codex docs say the CLI, desktop app and IDE extension run natively on Windows with a Windows sandbox, so WSL is not required [2]. Windows 11 is recommended. A fully updated Windows 10 (1809 or newer) is "best effort" [2].
One mismatch: the GitHub repo's install page still lists "Windows 11 via WSL2" as the requirement [10]. This guide follows the docs site.
Setup: native PowerShell
Open a new PowerShell window and run the standalone installer [1]:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Run the same command to update. It installs codex to %LOCALAPPDATA%\Programs\OpenAI\Codex\bin by default [8]. You can also use npm install -g @openai/codex [1][9]. The npm package declares Node.js 16 or newer [12].
The docs also expect winget to be available [2]. Then cd into a project and run codex to sign in [1].
Setup: WSL2
From an administrator PowerShell [4][13]:
wsl --install
wsl
wsl --install needs Windows 10 version 2004 (build 19041) or later, or Windows 11. It installs Ubuntu by default, and new installs use WSL 2 [13]. Then, inside the WSL shell [4]:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
What breaks, and the fix
Sandboxing and approvals
Approval modes work the same way on both. The default "Auto" preset is --sandbox workspace-write --ask-for-approval on-request. Codex can edit files and run commands in the workspace, and it asks before it edits outside the workspace or uses the network. Network access is off by default [5]. The older untrusted approval policy has been retired [5].
What differs is the sandbox underneath. Linux, including WSL2, uses bwrap plus seccomp. Native Windows uses MXC, with elevated and unelevated as legacy fallbacks [5].
Native Windows breaks:
- Elevated setup fails. The usual causes are a declined UAC prompt, or a machine that blocks creating local users, changing firewall rules or granting logon rights. Fix: retry and approve the prompt, or ask IT to allow those steps. If policy permits, use
unelevatedin the meantime [2]. It has weaker network isolation and doesn't support denied read paths [2]. - Error 1385. Windows policy is blocking the sandbox users from logging on. Ask IT to grant the logon rights. Use
unelevatedwhile they look, and send themCODEX_HOME/.sandbox/sandbox.log[2]. - "Folders writable by Everyone" warning. Remove
Everyonewrite access from the listed folders, then restart Codex [2]. - MXC isn't on by default in the CLI.
features.prefer_mxcis off by default in the standalone CLI [6]. MXC needs Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278), and Microsoft is still rolling out the capabilities it uses [2]. From 0.162.0 you can test it with one command [2]. Under MXC, leftover child processes stop when the foreground command exits, so test workflows that rely on detached dev servers [2]. - Sandbox stops working after you move a repo or change policies. Restart Codex. For MXC, run the compatibility test again. For
elevated, run sandbox setup again [2]. Version 0.169.0 fixed sandbox handling for quotedcmd.exepaths and for PowerShell sessions [11]. Version 0.170.0 keeps file permissions intact when Windows sandbox setup runs again [17]. So update first.
WSL breaks:
- WSL1. Codex 0.115 and later need WSL2, because the Linux sandbox moved to
bubblewrap[4]. Check withwsl -l -v. Convert withwsl --set-version <Distro> 2[13].
On either side, --dangerously-bypass-approvals-and-sandbox (alias --yolo) removes both the sandbox and the approval prompts. The docs mark it "not recommended" [5].
Paths and file access
The rule is to keep files on the same side as the agent. Microsoft says to store files in the WSL file system when you work from a Linux shell, and in the Windows file system when you work from PowerShell [14].
- Native agent: store projects on the Windows drive. Reach them from WSL through
/mnt/<drive>/...[3]. The Windows app docs list Git not being detected for projects opened from\\wsl$as a known issue, with that same fix [3]. - WSL agent: keep repos under
~/code./mnt/ccan be slower, and causes more symlink and permission problems [4]. Windows Explorer can still reach them at\\wsl$[4]. - Case sensitivity: Windows file names are case-insensitive. Linux file names are case-sensitive [14].
/mnt/c performance
If a large repo feels slow in WSL, move it out of /mnt/c first [4]. Then give WSL more resources, and update it with wsl --update followed by wsl --shutdown [4]. Memory and CPU are set in %UserProfile%\.wslconfig with memory and processors. By default WSL 2 gets 50% of Windows memory and all logical processors [15]. WSL picks up config changes only after it fully stops [15].
Line endings
Windows and Linux use different default line endings. If one repo folder is used from both, Git can show many files as modified with no real change [16]. Microsoft's fix is to turn off line-ending conversion, either in a .gitattributes file or globally on the Windows side [16]. The Codex docs don't cover line endings, as of 18 November 2026.
Node and npm
- PowerShell: if you've never run
npmin PowerShell, you may hitnpm.ps1 cannot be loaded because running scripts is disabled. The docs' common fix isSet-ExecutionPolicy -ExecutionPolicy RemoteSigned, after you read Microsoft's execution policy guide [3]. They suggestwinget install --id OpenJS.NodeJS.LTSfor Node [3]. - WSL: by default WSL adds Windows path entries to Linux
$PATH(appendWindowsPath, defaulttrue) [15]. Runwhich codexto confirm which binary runs [4]. To keep Windows paths out, setappendWindowsPath=falseunder[interop]in/etc/wsl.conf[15].
Environment variables
- Two Codex homes. Native Codex uses
%USERPROFILE%\.codex. Codex in WSL uses the Linux home, so config, auth and session history aren't shared [3]. Fix: sync the two, or setexport CODEX_HOME=/mnt/c/Users/<windows-user>/.codexin your WSL shell profile [3]. The directory must already exist [8]. - Sharing other variables. Use
WSLENVto pass variables between Windows and WSL. The/pflag translates paths between the two formats [14]. - Secrets reach commands.
shell_environment_policy.ignore_default_excludesdefaults totrue. So Codex does not strip variables whose names containKEY,SECRETorTOKENbefore it runs commands. Set it tofalse, or add filters, to keep them out [7].
Shells
The docs say the native Windows agent runs commands in PowerShell [3]. Setup scripts run in the agent's environment: WSL if the agent uses WSL, PowerShell otherwise [3]. From WSL, Windows tools need their extension (notepad.exe), and cmd built-ins need cmd.exe /C [14].
Comparison
| Native PowerShell | WSL2 | |
|---|---|---|
| Install | install.ps1 via PowerShell [1] | install.sh inside WSL [4] |
| Sandbox | MXC, or elevated / unelevated [5] | bwrap + seccomp [5] |
| Admin needed | For elevated setup [2] | For wsl --install [13] |
| Keep repos | Windows drive [3] | ~/code, not /mnt/c [4] |
| Codex home | %USERPROFILE%\.codex [3] | ~/.codex [3] |
| Windows version | 11 recommended; 10 (1809+) best effort [2] | 10 (2004+) or 11 for wsl --install [13] |
| Pick it when | Windows-native project and tools | Linux tooling, or repos already in WSL [4] |
We build SoluTerminal, a Windows app for running Claude Code and Codex side by side, in PowerShell or WSL panes. It's free during beta. soluterminal.com
Sources
All read on 18 November 2026.
- Codex CLI, install: learn.chatgpt.com/docs/cli
- Windows sandbox: learn.chatgpt.com/docs/windows/windows-sandbox
- ChatGPT desktop app for Windows (Windows-native agent, WSL, known issues): learn.chatgpt.com/docs/windows/windows-app
- WSL: learn.chatgpt.com/docs/windows/wsl
- Agent approvals and security: learn.chatgpt.com/docs/agent-approvals-security
- Configuration reference (
features.prefer_mxc): learn.chatgpt.com/docs/config-file/config-reference - Advanced configuration (shell environment policy): learn.chatgpt.com/docs/config-file/config-advanced
- Environment variables: learn.chatgpt.com/docs/config-file/environment-variables
- openai/codex on GitHub: README
- openai/codex install and system requirements: openai/codex on GitHub,
docs/install.md - Codex release 0.169.0 on GitHub (
rust-v0.169.0) - npm package manifest (
engines.node): openai/codex on GitHub,codex-cli/package.json - Microsoft, Install WSL: learn.microsoft.com/en-us/windows/wsl/install
- Microsoft, Working across file systems: learn.microsoft.com/en-us/windows/wsl/filesystems
- Microsoft, Advanced settings configuration in WSL: learn.microsoft.com/en-us/windows/wsl/wsl-config
- Microsoft, Get started using Git on WSL (line endings): learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-git
- Codex release 0.170.0 (#60943, "Preserve file permissions during repeated Windows sandbox setup") on GitHub (
rust-v0.170.0)