app/windows.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-05 00:34 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 

24## Customize for your dev setup

25 

26### Preferred editor

27 

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

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

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

31choice takes precedence.

32 

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

34 

35### Integrated terminal

36 

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

38installed, options include:

39 

40- PowerShell

41- Command Prompt

42- Git Bash

43- WSL

44 

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

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

47expecting the new default terminal to appear.

48 

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

50 

51## Windows Subsystem for Linux (WSL)

52 

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

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

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

56 

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

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

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

60want to open.

61 

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

63your Windows filesystem and accessing them from WSL through

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

65directly from the WSL filesystem.

66 

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

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

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

70place after restart.

71 

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

73 

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

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

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

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

78 

79## Useful developer tools

80 

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

82 

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

84 revert changes.

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

86 efficiently.

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

88 efficiently.

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

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

91 

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

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

94asking Codex to install them:

95 

96```powershell

97winget install --id Git.Git

98winget install --id OpenJS.NodeJS.LTS

99winget install --id Python.Python.3.14

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

101winget install --id GitHub.cli

102```

103 

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

105the app.

106 

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

108version you want.

109 

110## Troubleshooting and FAQ

111 

112### Run commands with elevated permissions

113 

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

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

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

117permission level.

118 

119### PowerShell execution policy blocks commands

120 

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

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

123 

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

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

126them.

127 

128An error may look something like this:

129 

130```text

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

132```

133 

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

135 

136```powershell

137Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

138```

139 

140For details and other options, check Microsoft's

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

142before changing the policy.

143 

144### Local environment scripts on Windows

145 

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

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

148set of actions for every platform.

149 

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

151Windows-specific actions.

152 

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

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

155 

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

157and PowerShell otherwise.

158 

159### Git features are unavailable

160 

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

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

163 

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

165 

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

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

168Codex or reboot.