DownloadCodex Unofficial guide
English

Use Codex with WSL2 on Windows

You can use Codex with WSL2 in two ways. In the ChatGPT desktop app, open Settings, switch the agent from Windows native to WSL, and restart the app. Or install the Codex CLI inside your WSL2 distribution with the Linux installer. WSL1 is not supported from Codex 0.115 onward, so convert your distribution to WSL2 first.

Applies to: Windows 11, WSL2, ChatGPT desktop app, Codex CLI

Before you start: make sure it’s WSL2

From PowerShell:

wsl -l -v

The VERSION column must say 2. If it says 1, convert the distribution with wsl --set-version <DistroName> 2. OpenAI’s docs say WSL1 was supported only through Codex 0.114. See the WSL1 error.

Option A: Desktop app with the agent in WSL

  1. Open Settings in the ChatGPT desktop app.
  2. Switch the agent from Windows native to WSL.
  3. Restart the app. The change doesn’t take effect until you do. Your projects stay in place.

The integrated terminal is configured separately. You can run the agent in WSL and still use PowerShell in the terminal, or use WSL for both.

Option B: Codex CLI inside WSL2

Open your WSL2 shell and use the Linux installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Share config, sign-in, and history between Windows and WSL

The Windows app keeps its Codex home at %USERPROFILE%\.codex. A CLI inside WSL uses ~/.codex by default, so the two don’t share settings, cached auth, or sessions. To share them, point WSL at the Windows directory:

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

Add that line to ~/.bashrc or ~/.zshrc to make it permanent.

Where to keep your projects

If you keep using the Windows-native agent, OpenAI recommends storing projects on the Windows drive and reaching them from WSL via /mnt/<drive>/.... Opening projects from \\wsl$\ works, but Git may not be detected. See the fix.

Questions people ask

Is WSL required for Codex on Windows?

No. Native Windows is the default for the desktop app, with a Windows sandbox, and the CLI has its own PowerShell installer. Use WSL2 only if your toolchain already lives in Linux.

Why doesn't my WSL CLI remember my desktop app login?

The CLI inside WSL uses your Linux home directory by default, while the Windows app uses %USERPROFILE%\.codex. Point WSL at the Windows directory with CODEX_HOME to share them.

Sources

We link to the official source for every instruction on this page. If anything here disagrees with them, trust the official source and tell us.

Read next