windows.md Codex Docs, 2026-04-08 18:32 UTC → 2026-05-14 21:00 UTC

3Use Codex on Windows with the native [Codex app](https://developers.openai.com/codex/app/windows), the3Use Codex on Windows with the native [Codex app](https://developers.openai.com/codex/app/windows), the

4[CLI](https://developers.openai.com/codex/cli), or the [IDE extension](https://developers.openai.com/codex/ide).4[CLI](https://developers.openai.com/codex/cli), or the [IDE extension](https://developers.openai.com/codex/ide).

5 5 

6[![](/images/codex/codex-banner-icon.webp)6The Codex app on Windows supports core workflows such as parallel agent threads,

7 7worktrees, automations, Git functionality, the in-app browser, artifact previews,

8Use the Codex app on Windows8plugins, and skills.

9 9 

10Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)10<div class="mb-8">

11 <CodexCallout

12 href="/codex/app/windows"

13 title="Use the Codex app on Windows"

14 description="Work across projects, run parallel agent threads, and review results in one place with the native Windows app."

15 iconSrc="/images/codex/codex-banner-icon.webp"

16 />

17</div>

11 18 

12Depending on the surface and your setup, Codex can run on Windows in three19Depending on the surface and your setup, Codex can run on Windows in three

13practical ways:20practical ways:

14 21 

15- natively on Windows with the stronger `elevated` sandbox,22- natively on Windows with the stronger `elevated` sandbox,

16- natively on Windows with the fallback `unelevated` sandbox,23- natively on Windows with the fallback `unelevated` sandbox,

17- or inside [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL), which uses the Linux sandbox implementation.24- or inside [Windows Subsystem for Linux 2](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), which uses the Linux sandbox implementation.

18 25 

19## Windows sandbox26## Windows sandbox

20 27 

32 39 

33`elevated` is the preferred native Windows sandbox. It uses dedicated40`elevated` is the preferred native Windows sandbox. It uses dedicated

34lower-privilege sandbox users, filesystem permission boundaries, firewall41lower-privilege sandbox users, filesystem permission boundaries, firewall

35rules, and local policy changes needed for sandboxed command execution.42rules, and local policy changes needed for commands that run in the sandbox.

36 43 

37`unelevated` is the fallback native Windows sandbox. It runs commands with a44`unelevated` is the fallback native Windows sandbox. It runs commands with a

38restricted Windows token derived from your current user, applies ACL-based45restricted Windows token derived from your current user, applies ACL-based

39filesystem boundaries, and uses environment-level offline controls instead of46filesystem boundaries, and uses environment-level offline controls instead of

40the dedicated offline-user firewall rule. It is weaker than `elevated`, but it47the dedicated offline-user firewall rule. It's weaker than `elevated`, but it

41is still useful when administrator-approved setup is blocked by local or48is still useful when administrator-approved setup is blocked by local or

42enterprise policy.49enterprise policy.

43 50 

64| Windows version | Support level | Notes |71| Windows version | Support level | Notes |

65| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |72| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

66| Windows 11 | Recommended | Best baseline for Codex on Windows. Use this if you are standardizing an enterprise deployment. |73| Windows 11 | Recommended | Best baseline for Codex on Windows. Use this if you are standardizing an enterprise deployment. |

67| Recent, fully updated Windows 10 | Best effort | Can work, but is less reliable than Windows 11. For Windows 10, Codex depends on modern console support, including ConPTY. In practice, Windows 10 October 2018 Update or newer is required. |74| Recent, fully updated Windows 10 | Best effort | Can work, but is less reliable than Windows 11. For Windows 10, Codex depends on modern console support, including ConPTY. In practice, Windows 10 version 1809 or newer is required. |

68| Older Windows 10 builds | Not recommended | More likely to miss required console components such as ConPTY and more likely to fail in enterprise setups. |75| Older Windows 10 builds | Not recommended | More likely to miss required console components such as ConPTY and more likely to fail in enterprise setups. |

69 76 

70Additional environment assumptions:77Additional environment assumptions:

71 78 

72- `winget` should be available. If it is missing, update Windows or install79- `winget` should be available. If it's missing, update Windows or install

73 the Windows Package Manager before setting up Codex.80 the Windows Package Manager before setting up Codex.

74- The recommended native sandbox depends on administrator-approved setup.81- The recommended native sandbox depends on administrator-approved setup.

75- Some enterprise-managed devices block the required setup steps even when the82- Some enterprise-managed devices block the required setup steps even when the

85 92 

86The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.93The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

87 94 

88We recommend using the native Windows sandbox by default. The native Windows sandbox will offer the best perfomance and highest speeds while keeping the same security. Choose WSL when you95Use the native Windows sandbox by default. The native Windows sandbox offers the best performance and highest speeds while keeping the same security. Choose WSL2 when you

89need a Linux-native environment on Windows, when your workflow already lives in96need a Linux-native environment on Windows, when your workflow already lives in

90WSL, or when neither native Windows sandbox mode meets your needs.97WSL2, or when neither native Windows sandbox mode meets your needs.

91 98 

92## Windows Subsystem for Linux99## Windows Subsystem for Linux

93 100 

94If you choose WSL, Codex runs inside the Linux environment instead of using the101If you choose WSL2, Codex runs inside the Linux environment instead of using the

95native Windows sandbox. This is useful if you need Linux-native tooling on102native Windows sandbox. This is useful if you need Linux-native tooling on

96Windows, if your repositories and developer workflow already live in WSL, or103Windows, if your repositories and developer workflow already live in WSL2, or

97if neither native Windows sandbox mode works for your environment.104if neither native Windows sandbox mode works for your environment.

98 105 

106WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

107sandbox moved to `bubblewrap`, so WSL1 is no longer supported.

108 

99### Launch VS Code from inside WSL109### Launch VS Code from inside WSL

100 110 

101For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).111For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).

127 137 

128 This prints your distribution name.138 This prints your distribution name.

129 139 

130If you don’t see “WSL: …” in the status bar, press `Ctrl+Shift+P`, pick140If you don't see "WSL: ..." in the status bar, press `Ctrl+Shift+P`, pick

131 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not141 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not

132 `C:\`) for best performance.142 `C:\`) for best performance.

133 143 

134If the Windows app or project picker does not show your WSL repository, type144If the Windows app or project picker does not show your WSL repository, type

135`\wsl$` into the file picker or Explorer, then navigate to your145 <code>\\wsl$</code> into the file picker or Explorer, then navigate to your

136 distro's home directory.146 distro's home directory.

137 147 

138### Use Codex CLI with WSL148### Use Codex CLI with WSL

164 174 

165### Working on code inside WSL175### Working on code inside WSL

166 176 

167- Working in Windows-mounted paths like `/mnt/c/…` can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like `~/code/my-app`) for faster I/O and fewer symlink and permission issues:177- Working in Windows-mounted paths like <code>/mnt/c/...</code> can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like <code>~/code/my-app</code>) for faster I/O and fewer symlink and permission issues:

168 

169 ```bash178 ```bash

170 mkdir -p ~/code && cd ~/code179 mkdir -p ~/code && cd ~/code

171 git clone https://github.com/your/repo.git180 git clone https://github.com/your/repo.git

172 cd repo181 cd repo

173 ```182 ```

174- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.183- If you need Windows access to files, they're under <code>\\wsl$\Ubuntu\home\&lt;user&gt;</code> in Explorer.

175 184 

176## Troubleshooting and FAQ185## Troubleshooting and FAQ

177 186 

312 321 

313Large repositories feel slow in WSL322Large repositories feel slow in WSL

314 323 

315- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).324- Make sure you're not working under <code>/mnt/c</code>. Move the repository to WSL (for example, <code>~/code/...</code>).

316- Increase memory and CPU for WSL if needed; update WSL to the latest version:325- Increase memory and CPU for WSL if needed; update WSL to the latest version:

317 

318 ```powershell326 ```powershell

319 wsl --update327 wsl --update

320 wsl --shutdown328 wsl --shutdown