Primary navigation

Running Codex on Windows

Best practices for running Codex on Windows

For best performance on Windows, install and use Windows Subsystem for Linux (WSL2).

Codex is trained to operate in Unix-style environments; running inside WSL2 gives you a Linux shell, unix-style semantics, and tooling that match how Codex is designed to work best.

For example, when running Codex CLI on Linux, the agent can take advantage of built-in Linux sandboxing to automatically edit files while constraining edits to your workspace or run commands network-disabled.

Install Codex in Windows Subsystem for Linux (WSL)

Run these commands in an elevated PowerShell or Windows Terminal:

# Install default Linux distribution (like Ubuntu)
wsl --install

# Start a shell inside of Windows Subsystem for Linux
wsl

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# Install Node.js in WSL
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# In a new tab or after exiting and running `wsl` again to install Node.js
nvm install 22

# Install and run Codex in WSL
npm i -g @openai/codex
codex

Work on code inside WSL

  • Working in Windows-mounted paths like /mnt/c/… can be slower than when working in them in Windows. Keep your repos under your Linux home directory (like ~/code/my-app) for faster I/O and fewer symlink/permission issues: 
    mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo
  • If you need Windows access to files, they’re under \wsl$\Ubuntu\home<user> in Explorer.

Running Codex on Windows: common patterns

For Codex CLI, start wsl then cd into your project and run codex to use of Linux-based sandboxing.

For Codex IDE extension, the default mode Chat will ask you to approve file edits and running commands. Or you can select Agent (full access) - exercise caution when using this as this allows the agent to run unsandboxed without approval.

Troubleshooting & FAQ

Installed extension, but it’s unreponsive

Your system may be missing C++ development tools, which some native dependencies require:

  • Visual Studio Build Tools (C++ workload)
  • Microsoft Visual C++ Redistributable (x64)
  • With winget: winget install --id Microsoft.VisualStudio.2022.BuildTools -e

Then fully restart VS Code after installation.

If it feels slow on large repos

  • Make sure you’re not working under /mnt/c. Move the repo to WSL (e.g., ~/code/…).
  • Allocate more memory/CPU to WSL if constrained; update WSL to latest: 
    wsl --update
wsl --shutdown

VS Code in WSL can’t find codex

Verify the binary exists and is on PATH inside WSL:

which codex || echo "codex not found"

If the binary is not found, try installing by following the instructions earlier in this guide.