How to Use Codex on Windows with WSL (2026)

OpenAI Codex CLI is a terminal-based AI coding assistant that can read your codebase, write code, run commands, and manage files -- all from the command line. The catch: it is designed for macOS and Linux. If you are on Windows, you need to run it through WSL (Windows Subsystem for Linux).

This guide walks you through the complete setup, from installing WSL to running Codex on your Windows machine.

What Is OpenAI Codex CLI?

Codex CLI is OpenAI's open-source command-line tool for AI-assisted software development. Think of it as a terminal-native coding agent that can:

Read and understand your entire project structure
Write, edit, and refactor code across multiple files
Run shell commands and interpret the output
Debug errors by reading logs and stack traces
Work with any programming language

It runs locally but uses OpenAI's API (or compatible endpoints) for the language model backend.

Prerequisites

Requirement	Details
Windows 10 (build 19041+) or Windows 11	WSL2 requires a recent Windows version
Administrator access	Needed for WSL installation
OpenAI API key	Get one at platform.openai.com
8+ GB RAM	WSL2 runs a real Linux kernel alongside Windows
Stable internet	Required for API calls to OpenAI

Step 1: Install WSL2

If you do not already have WSL2 installed, open PowerShell as Administrator and run:

wsl --install

This installs WSL2 with Ubuntu as the default distribution. Restart your computer when prompted.

After reboot, the Ubuntu terminal will open automatically. Set up your Linux username and password.

Verify WSL2 is running

# In PowerShell
wsl --list --verbose

You should see something like:

  NAME      STATE           VERSION
* Ubuntu    Running         2

If the VERSION column shows 1, upgrade to WSL2:

wsl --set-version Ubuntu 2

Step 2: Set Up the Linux Environment

Open your WSL terminal (search for "Ubuntu" in the Start menu) and update packages:

sudo apt update && sudo apt upgrade -y

Install Node.js

Codex CLI requires Node.js 18+. Install it via nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Reload shell config
source ~/.bashrc

# Install Node.js LTS
nvm install --lts

# Verify
node --version  # Should show v22.x or later
npm --version

Install Git (if not present)

sudo apt install -y git

Step 3: Install Codex CLI

Install Codex globally via npm:

npm install -g @openai/codex

Verify the installation:

codex --version

Step 4: Configure Your API Key

Codex needs an OpenAI API key to function. Set it as an environment variable:

# Add to your shell config for persistence
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Alternatively, create a .env file in your project directory:

echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env

Using a Different LLM Provider

Codex supports any OpenAI-compatible API. To use a different provider, set the base URL:

# Example: Using a local Ollama instance
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"

# Example: Using xAI Grok
export OPENAI_API_KEY="your-xai-key"
export OPENAI_BASE_URL="https://api.x.ai/v1"

Step 5: Access Your Windows Files

WSL can access your Windows file system through /mnt/c/. Your Windows projects are available at:

# Navigate to a Windows project directory
cd /mnt/c/Users/YourUsername/Projects/my-app

# List files
ls -la

For better performance, clone repositories directly into the WSL file system:

# WSL-native directory (much faster I/O)
cd ~
mkdir projects
cd projects
git clone https://github.com/your-repo/my-app.git

Important: File operations on /mnt/c/ are significantly slower than on the native WSL filesystem (~/). For best Codex performance, work in your WSL home directory.

Step 6: Run Codex

Navigate to your project directory and start Codex:

cd ~/projects/my-app

# Start Codex in interactive mode
codex

# Or give it a direct task
codex "Add error handling to all the API route handlers in this project"

Codex Autonomy Modes

Codex has three autonomy levels that control how much it can do without asking:

Mode	Flag	What It Can Do
Suggest	`--suggest`	Read files, suggest changes (default)
Auto-edit	`--auto-edit`	Read files, apply code changes
Full auto	`--full-auto`	Read files, edit code, run commands

# Let Codex make code changes automatically
codex --auto-edit "Refactor this Express app to use TypeScript"

# Let Codex run commands too (use with caution)
codex --full-auto "Set up ESLint and Prettier for this project, install dependencies, and fix all linting errors"

Practical Examples

Fix a bug from an error message:

codex "I'm getting 'TypeError: Cannot read property of undefined' on line 42 of src/utils/parser.ts. Fix it."

Add tests for existing code:

codex "Write unit tests for all functions in src/services/auth.ts using Jest"

Refactor a component:

codex "Convert the UserProfile class component in src/components/UserProfile.jsx to a functional component with hooks"

Troubleshooting Common Issues

"codex: command not found"

Make sure the npm global bin directory is in your PATH:

# Check where npm installs global packages
npm config get prefix

# Add to PATH if needed
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Slow file access

If Codex is slow when working with files on /mnt/c/, move your project to the WSL filesystem:

cp -r /mnt/c/Users/YourUsername/Projects/my-app ~/projects/my-app
cd ~/projects/my-app

WSL memory usage

WSL2 can consume a lot of memory. Create a .wslconfig file in your Windows home directory to limit it:

# C:\Users\YourUsername\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB

Restart WSL after changing the config:

# In PowerShell
wsl --shutdown

Network issues (API calls failing)

If Codex cannot reach the OpenAI API, check your DNS settings in WSL:

# Check if DNS resolution works
nslookup api.openai.com

# If it fails, fix DNS
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "[network]\ngenerateResolvConf = false" > /etc/wsl.conf'

GUI applications and clipboard

To copy Codex output to your Windows clipboard:

# Pipe output to Windows clipboard
codex "explain this function" | clip.exe

# Or install xclip for bidirectional clipboard
sudo apt install -y xclip

VS Code Integration

For the best experience, use VS Code with the WSL extension:

Install the "WSL" extension in VS Code
Open your WSL project with code . from the WSL terminal
VS Code's integrated terminal will use WSL automatically
Run Codex directly in the VS Code terminal

# From your WSL project directory
code .

# Then in VS Code's terminal (which is now WSL)
codex "Add a README with setup instructions for this project"

Codex vs. Other AI Coding Tools

Feature	Codex CLI	Claude Code	Cursor	GitHub Copilot
Interface	Terminal	Terminal	IDE	IDE
File editing	Yes	Yes	Yes	Suggestions only
Command execution	Yes	Yes	Limited	No
WSL support	Via WSL	Via WSL	Native	Native
Open source	Yes	No	No	No
Model flexibility	Any OpenAI-compatible	Claude only	Multiple	GPT-based
Offline mode	No (needs API)	No	No	No
Price	API costs only	Claude subscription	$20+/month	$10+/month

Wrapping Up

Running Codex on Windows through WSL gives you the same experience as macOS and Linux users. The setup takes about 15 minutes and the WSL2 integration is mature enough that you will barely notice the difference. For the best performance, keep your project files on the WSL filesystem rather than accessing Windows drives.

If your projects involve AI-generated media alongside code, check out Hypereal AI for a unified API that handles image generation, video, talking avatars, and more.

Try Hypereal AI free -- 35 credits, no credit card required.