FAQ

Using Codex on Windows

Native or WSL2, sandbox modes, the PowerShell execution policy and garbled Chinese text, and how to share config between WSL and Windows.

Native or WSL2

	Native Windows	WSL2
Where Codex runs commands	PowerShell, isolated by the Windows sandbox	A Linux environment, isolated by the Linux sandbox
Good for	Ordinary Windows projects. The desktop app uses this by default	Projects that depend on a Linux toolchain, or that already live in WSL
Requirements	Windows 11 recommended. Windows 10 needs version 1809 or later	WSL2 only. WSL1 is no longer supported as of Codex 0.115

If you’re not sure, start with native. Switch to WSL2 when you run into Linux-only tools.

Native: the sandbox

On Windows, Codex uses a sandbox to limit which files commands can read and write, and whether they can access the network. There are three sandbox implementations, and Codex picks one automatically:

mxc: recommended. On compatible devices it needs no admin setup.
elevated: the first choice when mxc isn’t available. The first time, an administrator has to approve the setup. After that, commands themselves don’t run as administrator. In the CLI, you can complete the setup with /setup-default-sandbox.
unelevated: the last resort, for when company policy blocks the admin setup. Its network isolation is weaker than elevated.

To choose one yourself, write this in config.toml:

[windows]
sandbox = "elevated" # or "unelevated"

In the desktop app, the sandbox only takes effect when you choose Ask for approval below the input box. For commands that really need administrator rights, right-click the ChatGPT desktop app and choose Run as administrator. Codex inherits that permission.

Error 1385: Windows policy doesn’t allow the sandbox user to start commands. On a company computer, first ask IT to check the logon rights. If you need it working right away, switch to unelevated for now. The log for troubleshooting is at %USERPROFILE%\.codex\.sandbox\sandbox.log.

PowerShell blocks scripts

The error looks like this (the second line is the same error on a Chinese-language system):

npm.ps1 cannot be loaded because running scripts is disabled on this system.
无法加载文件 C:\Users\...\codex.ps1，因为在此系统上禁止运行脚本。

By default, PowerShell doesn’t allow scripts to run. Allow them for the current user only. This doesn’t need administrator rights:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

If you don’t want to change the policy, use codex.cmd instead of codex. Before you change it, you can read Microsoft’s explanation of execution policies.

PowerShell 7 and garbled Chinese text

Windows comes with PowerShell 5.1. Chinese output is often garbled in it, and some commands behave differently from newer versions. We recommend installing PowerShell 7:

winget install --id Microsoft.PowerShell -e

After installing, open your terminal with PowerShell 7 (pwsh). If text is still garbled, run notepad $PROFILE to open your PowerShell profile and add these two lines:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

We don’t recommend turning on Beta: Use Unicode UTF-8 for worldwide language support in system settings. It affects other software.

In the desktop app’s settings, you can change the built-in terminal to PowerShell, Command Prompt, Git Bash or WSL. The change only applies to terminals you open afterwards.

Install common tools

Codex uses these tools while it works. Git is required, because the desktop app’s change review relies on it:

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id GitHub.cli

After installing the GitHub CLI, run gh auth login once. Only then do the GitHub-related features in the desktop app work.

Use WSL2

Open PowerShell as administrator and install WSL (it installs Ubuntu by default). When it’s done, restart your computer as prompted:
Terminal window
```
wsl --install
```
Open WSL. First install bubblewrap, which the Codex sandbox depends on, then install and start Codex:
Terminal window
```
sudo apt install bubblewrap
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
```

Where to put your projects:

If Codex runs in WSL (the CLI inside WSL, or the desktop app with its agent switched to WSL): put projects in a Linux directory, such as ~/code/project-name. Under /mnt/c/... they are slow and tend to run into permission and symlink problems.
If you use the native Windows desktop app and also need to work on the project in WSL: OpenAI recommends keeping the project on the Windows drive and reaching it from WSL through /mnt/c/.... Git sometimes doesn’t recognize projects opened directly from \\wsl$.

Switch the desktop app to WSL: Open settings, switch the agent from Windows native to WSL, then restart the ChatGPT desktop app. The change takes effect only after the restart.

Share config between WSL and Windows: The desktop app and the CLI on Windows use %USERPROFILE%\.codex. The CLI in WSL uses Linux’s ~/.codex by default. They don’t share sign-in, config or session history. To share them, add one line to ~/.bashrc (or ~/.zshrc) in WSL, replacing your-username with your Windows user name:

export CODEX_HOME=/mnt/c/Users/your-username/.codex

VS Code with WSL: In WSL, go to the project directory and run code .. VS Code opens in WSL mode and shows WSL: Ubuntu in the bottom-left corner. The Codex extension then runs in WSL too. If you don’t want to use a WSL window, you can instead turn on chatgpt.runCodexInWindowsSubsystemForLinux in VS Code settings, so the extension runs Codex in WSL.

This page follows OpenAI’s official documentation, checked in October 2026. OpenAI updates often, so button names and menu locations may differ slightly. Go by what you see on screen.