Windows setup
Codex on Windows: the app or the CLI, and how to set up each one
Updated November 17, 20268 min read
Codex on Windows runs natively in PowerShell with no WSL needed, and it comes in two forms: the Codex app inside the ChatGPT desktop app, and the Codex CLI that you type into a terminal. The table below shows how the two differ. After that, one section sets up each, then come the Windows problems worth knowing about and a way to run Codex beside Claude Code.
Codex app vs Codex CLI on Windows, side by side
| Codex app | Codex CLI | |
|---|---|---|
| What it is | A window inside the ChatGPT desktop app for projects, parallel chats and reviewing changes | The codex command, running in your terminal |
| How you install it | Microsoft Store, or winget install --id 9PLM9XGG6VKS -s msstore | OpenAI's PowerShell installer, or npm install -g @openai/codex |
| Where the agent runs | Windows native by default. You can switch it to WSL in Settings | Wherever you start it: PowerShell, or inside WSL2 |
| Extras built in | Worktrees, a built-in browser, a review pane and a terminal panel | Slash commands, codex exec for scripts, codex resume, MCP servers |
| Plans that include it (as of November 2026) | Free and Go get Codex in the desktop app for lighter tasks, subject to rollout. Plus and up get more | ChatGPT Plus ($20/month) and higher, or an OpenAI API key |
| Best for | People who would rather click than type | People who live in a terminal or want to script Codex |
Both sign in with the same ChatGPT account, so you can install both and switch whenever you like. OpenAI's Windows docs say the app and the CLI both run natively on Windows with PowerShell and a Windows sandbox (a safety fence that limits which files and network access Codex gets).
Windows 11 is recommended. A fully updated Windows 10, version 1809 or newer, is supported on a best-effort basis. That version matters because it added ConPTY, the Windows feature that lets a program act like a real terminal.
Setting up the Codex app on Windows
- 1
Install the ChatGPT desktop app
The Codex app on Windows lives inside the ChatGPT desktop app. Get it from the Microsoft Store, or paste the first command below into PowerShell.
- 2
Add the developer tools Codex leans on
OpenAI says Codex works best with a few common tools already installed. Git matters most: without it, some app features do not work. The second code block installs Git, Node.js, Python, the .NET SDK and GitHub CLI with WinGet.
- 3
Connect GitHub
After GitHub CLI installs, run
gh auth loginand follow the prompts. That turns on the app's GitHub features. - 4
Sign in and add a project
Open the app, sign in with your ChatGPT account and add the folder you want Codex to work in.
- 5
Pick native or WSL
Codex runs its agent natively by default. To use WSL instead, open Settings, switch the agent from Windows native to WSL, then restart the app. The change only applies after a restart.
- 6
Choose a terminal shell
The built-in terminal can use PowerShell, Command Prompt, Git Bash or WSL, depending on what you have installed. This is set separately from where the agent runs.
winget install --id 9PLM9XGG6VKS -s msstorewinget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id Microsoft.DotNet.SDK.10
winget install --id GitHub.cliTo keep the sandbox switched on in the app, choose Ask for approval under the message box. You only need the tools for languages you actually use, so skip Python or .NET if your projects never touch them.
Installing the Codex CLI in PowerShell
- 1
Open a new PowerShell window
A normal window is fine. You do not need to run it as Administrator.
- 2
Run OpenAI's Windows installer
Paste the first command below. The
-ExecutionPolicy ByPasspart lets the script run once without changing your PC's settings. - 3
Or use npm if you already have Node.js
The npm package installs the same CLI. Pick one method, not both, so you always know which copy is running.
- 4
Start it in your project and sign in
Use
cdto move into the project folder, typecodexand choose Sign in with ChatGPT. You can also sign in with an OpenAI API key, billed per use. - 5
Give it a first task
Try
Tell me about this project. When Codex wants to run a command or edit a file, it asks first unless you change its permissions with/permissions.
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"npm install -g @openai/codexTo update later, run the same install command again. If something feels off, codex doctor checks your setup. Our Codex CLI guide covers the commands and slash commands in more depth.
Where the Codex CLI keeps its files on Windows
- Your personal settings:
%USERPROFILE%\.codex\config.toml. This is where you set defaults such as the model or sandbox type. - Settings for one project: a
.codex\config.tomlfile inside the project. Codex only loads it for projects you have marked as trusted. - Project instructions: an
AGENTS.mdfile in the project folder. Type/initin a session and Codex writes a first version for you. Add your build command, your test command and anything Codex must never touch.
For scripts or scheduled jobs, codex exec "your task" runs a task from start to finish without asking you anything. Keep that for projects you have committed to git, since nobody is there to say no.
Running the Codex CLI inside WSL
- Open PowerShell as Administrator, run
wsl --installand restart. - Open Ubuntu from the Start menu and create your Linux user.
- Install Codex inside Ubuntu with the Linux command below.
- Keep your project on the Windows drive and open it from WSL through
/mnt/c/.... OpenAI suggests this because Git detection is more reliable that way.
curl -fsSL https://chatgpt.com/codex/install.sh | shA Codex CLI inside WSL does not automatically share its settings, saved sign-in or chat history with the Windows app. OpenAI's docs describe syncing them or pointing both at one folder with the CODEX_HOME setting.
Codex Windows issues to know before you start
Watch out
Full access mode turns the sandbox off. OpenAI notes that Codex is then no longer limited to your project folder, so one bad command can reach other files. Only turn it on for a project you have committed to git or backed up.
Watch out
Starting the app as Administrator gives the agent Administrator rights too, because it inherits the app's permission level. Open it normally unless a task truly needs more.
Note
WSL1 is no longer supported. It worked up to Codex 0.114. From 0.115 you need WSL2.
The rest are smaller snags with known fixes, all taken from OpenAI's Windows and sandbox pages:
- `npm.ps1 cannot be loaded because running scripts is disabled on this system`: PowerShell is blocking script launchers. OpenAI suggests
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned. - Git not detected for a project stored inside WSL: move the project to your Windows drive and reach it through
/mnt/<drive>/.... - The sandbox setup fails: one sandbox option needs a one-time admin approval. Clicking No on the Windows UAC popup (the "allow this app to make changes" box) is a common cause. Run the setup again and approve it.
- Error 1385: Windows policy is blocking the sign-in type the sandbox user needs. On a work PC, ask your IT team.
- A warning that some folders are writable by Everyone: the sandbox cannot fully protect those folders. Keep projects somewhere only your user can write.
- A dev server stops on its own: with the newest sandbox type, called
mxc, child programs end when the main command exits, so a detached development server may not keep running. - Cmder missing from the Open dialog: add Cmder to the Start menu, then restart Codex or the PC.
The mxc sandbox is the one OpenAI recommends, and it needs no admin setup, but only on Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278) with Microsoft's newer features rolled out. Older PCs fall back to the admin-approved sandbox. Managed work laptops sometimes block setup even on a supported version, and OpenAI also expects winget to be available.
Using Codex next to Claude Code on one Windows PC
You can keep both agents on one PC. Some people give Codex one kind of job and Claude Code another, or ask one to check the other's work. They install side by side without conflict. Here is where they differ day to day:
| Task | Codex | Claude Code |
|---|---|---|
| Install in PowerShell | The powershell -ExecutionPolicy ByPass command shown earlier | irm https://claude.ai/install.ps1 | iex |
| Project notes file | AGENTS.md | CLAUDE.md |
| Create the notes file | /init | /init |
| Change what it may do alone | /permissions | Shift+Tab to cycle modes |
| Pick up an old chat | codex resume | claude -r |
Moving between them is easier than it used to be. Codex has an /import command that brings in your Claude Code settings and chats. Going the other way, Claude Code (version 2.1.277 or later) reads a project's AGENTS.md when the project has no CLAUDE.md, so one notes file can serve both agents. The Claude Code on Windows page covers that side of the install.
One rule matters more than any setting: never let two agents edit the same files at once. Give each its own folder, or a git worktree (a second copy of your project that git keeps linked to the first). Our worktrees guide shows how, and Codex vs Claude Code helps you decide which job suits which agent.
The Codex app is good at running Codex, but it does not show your Claude sessions. VibeCodingDeck is one Windows app around both: Codex in one pane and Claude Code in the next, up to 12 at once, a status light that turns to waiting when an agent needs you, a usage meter for each ChatGPT and Claude login, and a button to hand a stuck job to the other AI. It uses your own subscriptions and costs $29/month or $249/year as of November 2026 (see pricing).
Codex on Windows: what people ask
Does Codex work on Windows without WSL?
+
Yes. As of November 2026 both the Codex app and the Codex CLI run natively in PowerShell with a Windows sandbox. WSL2 is an option, not a requirement.
Where do I download the Codex desktop app for Windows?
+
Codex on Windows is part of the ChatGPT desktop app. Install it from the Microsoft Store or run winget install --id 9PLM9XGG6VKS -s msstore in PowerShell.
Is the Codex app free on Windows?
+
ChatGPT Free and Go plans include Codex in the desktop app for lighter tasks, subject to rollout. The CLI and heavier use start with ChatGPT Plus at $20/month, as of November 2026.
Can I use the Codex CLI and the Codex app at the same time?
+
Yes. They share your ChatGPT account. A CLI installed inside WSL keeps its own settings and history unless you point both at one folder with CODEX_HOME.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Command reference
Codex CLI command reference: from install to codex exec
Head to head
Codex vs Claude Code: seven rounds and an honest verdict
Windows install guide
Claude Code Windows install: choose your method, then get it running
Explainer
AI agent orchestration for coding: the words, the patterns and a worked example
Three-way comparison
Claude Code vs Codex vs Gemini: the three CLI coding agents compared