app/windows.md Codex Docs, 2026-02-27 18:15 UTC → 2026-03-05 06:22 UTC

1# Windows

2 

3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl).

8 

9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

10 

11## Download and update the Codex app

12 

13Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).

15 

16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

17 

18To update the app, open the Microsoft Store, go to **Downloads**, and click

19**Check for updates**. The Store installs the latest version afterward.

20 

21For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.

23 

24If you prefer a command-line install path, or need an alternative to opening

25the Microsoft Store UI, run:

26 

27```powershell

28winget install --id 9PLM9XGG6VKS

29```

30 

31## Customize for your dev setup

32 

33### Preferred editor

34 

35Choose a default app for **Open**, such as Visual Studio, VS Code, or another

36editor. You can override that choice per project. If you already picked a

37different app from the **Open** menu for a project, that project-specific

38choice takes precedence.

39 

40![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)

41 

42### Integrated terminal

43 

44You can also choose the default integrated terminal. Depending on what you have

45installed, options include:

46 

47- PowerShell

48- Command Prompt

49- Git Bash

50- WSL

51 

52This change applies only to new terminal sessions. If you already have an

53integrated terminal open, restart the app or start a new thread before

54expecting the new default terminal to appear.

55 

56![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)

57 

58## Windows Subsystem for Linux (WSL)

59 

60By default, the Codex app uses the Windows-native agent. That means the agent

61runs commands in PowerShell. The app can still work with projects that live in

62Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.

63 

64If you want to add a project from the WSL filesystem, click **Add new project**

65or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

66Explorer window. From there, choose your Linux distribution and the folder you

67want to open.

68 

69If you plan to keep using the Windows-native agent, prefer storing projects on

70your Windows filesystem and accessing them from WSL through

71`/mnt/<drive>/...`. This setup is more reliable than opening projects

72directly from the WSL filesystem.

73 

74If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,

75switch the agent from Windows native to WSL, and **restart the app**. The

76change doesn't take effect until you restart. Your projects should remain in

77place after restart.

78 

79![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

80 

81You configure the integrated terminal independently from the agent. See

82[Customize for your dev setup](#customize-for-your-dev-setup) for the

83terminal options. You can keep the agent in WSL and still use PowerShell in the

84terminal, or use WSL for both, depending on your workflow.

85 

86## Useful developer tools

87 

88Codex works best when a few common developer tools are already installed:

89 

90- **Git**: Powers the review panel in the Codex app and lets you inspect or

91 revert changes.

92- **Node.js**: A common tool that the agent uses to perform tasks more

93 efficiently.

94- **Python**: A common tool that the agent uses to perform tasks more

95 efficiently.

96- **.NET SDK**: Useful when you want to build native Windows apps.

97- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.

98 

99Install them with the default Windows package manager `winget` by pasting this

100into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or

101asking Codex to install them:

102 

103```powershell

104winget install --id Git.Git

105winget install --id OpenJS.NodeJS.LTS

106winget install --id Python.Python.3.14

107winget install --id Microsoft.DotNet.SDK.10

108winget install --id GitHub.cli

109```

110 

111After installing GitHub CLI, run `gh auth login` to enable GitHub features in

112the app.

113 

114If you need a different Python or .NET version, change the package IDs to the

115version you want.

116 

117## Troubleshooting and FAQ

118 

119### Run commands with elevated permissions

120 

121If you need Codex to run commands with elevated permissions, start the Codex app

122itself as an administrator. After installation, open the Start menu, find

123Codex, and choose Run as administrator. The Codex agent inherits that

124permission level.

125 

126### PowerShell execution policy blocks commands

127 

128If you have never used tools such as Node.js or `npm` in PowerShell before, the

129Codex agent or integrated terminal may hit execution policy errors.

130 

131This can also happen if Codex creates PowerShell scripts for you. In that case,

132you may need a less restrictive execution policy before PowerShell will run

133them.

134 

135An error may look something like this:

136 

137```text

138npm.ps1 cannot be loaded because running scripts is disabled on this system.

139```

140 

141A common fix is to set the execution policy to `RemoteSigned`:

142 

143```powershell

144Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

145```

146 

147For details and other options, check Microsoft's

148[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)

149before changing the policy.

150 

151### Local environment scripts on Windows

152 

153If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform

154commands such as `npm` scripts, you can keep one shared setup script or

155set of actions for every platform.

156 

157If you need Windows-specific behavior, create Windows-specific setup scripts or

158Windows-specific actions.

159 

160Actions run in the environment used by your integrated terminal. See

161[Customize for your dev setup](#customize-for-your-dev-setup).

162 

163Local setup scripts run in the agent environment: WSL if the agent uses WSL,

164and PowerShell otherwise.

165 

166### Share config, auth, and sessions with WSL

167 

168The Windows app uses the same Codex home directory as native Codex on Windows:

169`%USERPROFILE%\.codex`.

170 

171If you also run the Codex CLI inside WSL, the CLI uses the Linux home

172directory by default, so it does not automatically share configuration, cached

173auth, or session history with the Windows app.

174 

175To share them, use one of these approaches:

176 

177- Sync WSL `~/.codex` with `%USERPROFILE%\.codex` on your file system.

178- Point WSL at the Windows Codex home directory by setting `CODEX_HOME`:

179 

180```bash

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

182```

183 

184If you want that setting in every shell, add it to your WSL shell profile, such

185as `~/.bashrc` or `~/.zshrc`.

186 

187### Git features are unavailable

188 

189If you don't have Git installed natively on Windows, the app can't use some

190features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.

191 

192### Git isn't detected for projects opened from `\\wsl$`

193 

194For now, if you want to use the Windows-native agent with a project that is

195also accessible from WSL, the most reliable workaround is to store the project

196on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.

197 

198### Cmder is not listed in the open dialog

199 

200If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the

201Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart

202Codex or reboot.