Guides

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:

WSL breaks:

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].

/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

Environment variables

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
Installinstall.ps1 via PowerShell [1]install.sh inside WSL [4]
SandboxMXC, or elevated / unelevated [5]bwrap + seccomp [5]
Admin neededFor elevated setup [2]For wsl --install [13]
Keep reposWindows drive [3]~/code, not /mnt/c [4]
Codex home%USERPROFILE%\.codex [3]~/.codex [3]
Windows version11 recommended; 10 (1809+) best effort [2]10 (2004+) or 11 for wsl --install [13]
Pick it whenWindows-native project and toolsLinux 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.

  1. Codex CLI, install: learn.chatgpt.com/docs/cli
  2. Windows sandbox: learn.chatgpt.com/docs/windows/windows-sandbox
  3. ChatGPT desktop app for Windows (Windows-native agent, WSL, known issues): learn.chatgpt.com/docs/windows/windows-app
  4. WSL: learn.chatgpt.com/docs/windows/wsl
  5. Agent approvals and security: learn.chatgpt.com/docs/agent-approvals-security
  6. Configuration reference (features.prefer_mxc): learn.chatgpt.com/docs/config-file/config-reference
  7. Advanced configuration (shell environment policy): learn.chatgpt.com/docs/config-file/config-advanced
  8. Environment variables: learn.chatgpt.com/docs/config-file/environment-variables
  9. openai/codex on GitHub: README
  10. openai/codex install and system requirements: openai/codex on GitHub, docs/install.md
  11. Codex release 0.169.0 on GitHub (rust-v0.169.0)
  12. npm package manifest (engines.node): openai/codex on GitHub, codex-cli/package.json
  13. Microsoft, Install WSL: learn.microsoft.com/en-us/windows/wsl/install
  14. Microsoft, Working across file systems: learn.microsoft.com/en-us/windows/wsl/filesystems
  15. Microsoft, Advanced settings configuration in WSL: learn.microsoft.com/en-us/windows/wsl/wsl-config
  16. Microsoft, Get started using Git on WSL (line endings): learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-git
  17. Codex release 0.170.0 (#60943, "Preserve file permissions during repeated Windows sandbox setup") on GitHub (rust-v0.170.0)

Keys on this page

The page's main button
D
This list
?

In the demo

Answer a waiting prompt
123YN⏎Esc
Open folded tool calls
CtrlO
Previous / next chapter
← →
Single-key shortcuts