# Using Codex on 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`:

```toml title="%USERPROFILE%\\.codex\\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):

```text
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:

```powershell
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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_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:

```powershell
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:

```powershell
[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:

```powershell
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

1. Open PowerShell as administrator and install WSL (it installs Ubuntu by default). When it's done, restart your computer as prompted:

   ```powershell
   wsl --install
   ```

2. Open WSL. First install bubblewrap, which the Codex sandbox depends on, then install and start Codex:

   ```bash
   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:

```bash
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.