Comprehensive Guide to Installing Codex CLI on Windows

Introduction

OpenAI’s Codex CLI brings powerful AI-assisted coding directly to your Windows terminal. This comprehensive guide covers everything you need to know about installing and running Codex on Windows 10 and Windows 11, including both WSL (Windows Subsystem for Linux) and native Windows installations.

Whether you’re a developer looking to boost productivity, automate coding tasks, or explore AI-powered development tools, this guide will get you up and running with Codex CLI on Windows.

---

What is Codex CLI?

Codex CLI is OpenAI’s open-source, lightweight coding agent that runs directly in your terminal. Built in Rust for speed and efficiency, it leverages advanced language models like GPT-5.2-Codex to:

• Generate Code: Create complete applications from natural language prompts
• Debug Issues: Identify and fix bugs automatically
• Refactor Projects: Modernize and optimize existing codebases
• Execute Commands: Run tasks safely in your local environment
• Review Code: Get AI-powered code reviews before committing

All operations happen locally on your machine, ensuring your proprietary code never leaves your environment.

---

Windows Compatibility Notice

⚠️ Important: As of January 2026, Windows support for Codex CLI is experimental.

Current Status

• Native Windows: Functional but may have compatibility issues, especially on Windows 10
• WSL2 (Recommended): Provides the best experience with full Linux compatibility
• Windows 11: Better native support than Windows 10, but WSL2 still recommended

Why WSL2?

WSL2 offers several advantages for Codex on Windows:

• Stable Environment: Linux-like semantics that match training data
• Better Performance: Faster I/O and fewer permission issues
• Tool Compatibility: Seamless integration with Unix tools and shells
• Proven Reliability: Most issues resolved in the Linux environment

Windows Sandbox Limitations

When running natively on Windows, Codex uses an experimental sandbox that:

• ✅ Blocks filesystem writes outside the working folder
• ✅ Prevents network access without approval
• ❌ Cannot prevent writes to world-writable directories
• ⚠️ May have compatibility issues with some Windows configurations

---

Prerequisites

System Requirements

• Operating System: Windows 10 (version 2004 or higher) or Windows 11
• RAM: Minimum 4GB, 8GB recommended
• Storage: At least 1GB free space
• Internet Connection: Required for API communication

Required Software

1. Node.js (v18 or higher)
2. npm (comes with Node.js)
3. Git (recommended)
4. WSL2 (for WSL installation method)

OpenAI Account

You’ll need:

• A ChatGPT Plus, Pro, Business, Edu, or Enterprise account, OR
• An OpenAI API key with appropriate credits

---

Installation Methods

Method 1: WSL Installation (Recommended)

This method provides the best Codex experience on Windows by leveraging Windows Subsystem for Linux.

Step 1: Enable and Install WSL2

Open PowerShell as Administrator and run:

# Install WSL with Ubuntu (default)
wsl --install

# Or install with a specific distro
wsl --install -d Ubuntu

Note: You’ll need to restart your computer after installation.

Step 2: Verify WSL Installation

After restarting, open PowerShell and check the status:

# Check WSL version
wsl --status

# Ensure you're using WSL 2
wsl --set-default-version 2

Step 3: Update WSL

Keep WSL updated for the best experience:

# Update WSL kernel
wsl --update

Step 4: Launch Ubuntu

Open the Start Menu, search for “Ubuntu” or “WSL”, and launch the terminal.

Step 5: Install Node.js in WSL

Inside your WSL terminal, install Node.js using NVM:

# Install NVM (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install Node.js LTS
nvm install 22

# Verify installation
node --version
npm --version

Step 6: Install Git in WSL

# Install Git
sudo apt update
sudo apt install -y git

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Step 7: Install Codex CLI in WSL

# Install Codex globally
npm install -g @openai/codex

# Verify installation
codex --version

Step 8: Set Up Your Workspace

Keep your projects in the Linux filesystem for best performance:

# Create a workspace directory
mkdir -p ~/code
cd ~/code

# Clone or create your project
git clone https://github.com/your/repo.git
cd repo

Important: Avoid working in /mnt/c/ paths (Windows-mounted drives) as they’re slower and can cause permission issues.

Step 9: Access Files from Windows

Your WSL files are accessible from Windows File Explorer at:

\\wsl$\Ubuntu\home\<username>

Or type \\wsl$ in the address bar to see all WSL distributions.

---

Method 2: Native Windows Installation

While WSL is recommended, you can install Codex natively on Windows.

Step 1: Install Node.js

1. Visit https://nodejs.org/
2. Download the LTS version (Long Term Support)
3. Run the installer (.msi file)
4. Follow the installation wizard (keep default settings)

Step 2: Verify Node.js Installation

Open PowerShell or Command Prompt:

# Check Node.js version
node --version

# Check npm version
npm --version

Both should display version numbers (Node.js 18+ required).

Step 3: Install Git for Windows

1. Download from https://git-scm.com/download/win
2. Run the installer
3. Use recommended settings during installation

Step 4: Install Codex CLI

Open PowerShell and run:

# Install Codex globally
npm install -g @openai/codex

# Verify installation
codex --version

Step 5: Handle Missing C++ Build Tools (If Needed)

If you encounter errors about missing C++ tools:

1. Download Visual Studio Build Tools
2. Install “Desktop development with C++”
3. Restart PowerShell after installation

---

Authentication Setup

After installation, you need to authenticate Codex with OpenAI.

Option 1: ChatGPT Account Login (Recommended)

Run Codex for the first time:

# WSL or PowerShell
codex

You’ll be prompted to authenticate:

1. A browser window will open automatically
2. Sign in with your ChatGPT account
3. Grant Codex access
4. Return to the terminal

WSL Note: If the browser doesn’t open automatically, install WSL utilities:

# In WSL terminal
sudo apt install wslu -y

Option 2: API Key Authentication

Create Configuration Directory

In PowerShell (for native Windows):

# Create .codex directory
New-Item -Path "$env:USERPROFILE\.codex" -ItemType Directory -Force

In WSL:

# Create .codex directory
mkdir -p ~/.codex

Set Up API Key

In PowerShell:

# Set environment variable (temporary)
$env:OPENAI_API_KEY = "your-api-key-here"

# Make it permanent (add to PowerShell profile)
Add-Content -Path $PROFILE -Value '$env:OPENAI_API_KEY = "your-api-key-here"'

In WSL:

# Set environment variable
export OPENAI_API_KEY="your-api-key-here"

# Make it permanent
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Verify Authentication

# Check login status
codex login status

---

Configuration

Codex stores its configuration in a config.toml file.

Location

• Windows: C:\Users\<username>\.codex\config.toml
• WSL: ~/.codex/config.toml

Create Basic Configuration

In PowerShell:

# Create config.toml
@"
model = "gpt-5.2-codex"
model_provider = "openai"

[security]

sandbox_enabled = true confirm_before_execution = true

[internet]

enabled = false “@ | Out-File -FilePath “$env:USERPROFILE\.codex\config.toml” -Encoding UTF8

In WSL:

# Create config.toml
cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.2-codex"
model_provider = "openai"

[security]

sandbox_enabled = true confirm_before_execution = true

[internet]

enabled = false EOF

Advanced Configuration Options

# Model settings
model = "gpt-5.2-codex"
model_reasoning_effort = "high"

# Working directory
workspace_root = "C:\\Users\\YourName\\Projects"  # Windows
# OR
workspace_root = "/home/username/code"  # WSL

# Execution policy

[execution]

approval_mode = “on-request” # Options: always, on-request, never sandbox_mode = “workspace-write” # Options: none, read-only, workspace-write # Internet access

[internet]

enabled = false allowed_domains = [“pypi.org”, “npmjs.com”, “github.com”] allowed_methods = [“GET”, “POST”] # Security

[security]

sandbox_enabled = true confirm_before_execution = true max_file_size_mb = 10

---

Getting Started with Codex

Launch Codex

In WSL or PowerShell:

# Navigate to your project
cd ~/code/my-project  # WSL
cd C:\Users\YourName\Projects\my-project  # Windows

# Start Codex
codex

Basic Commands

Once inside Codex:

• /model – Switch between available models
• /status – Check workspace, model, and token usage
• /help – Display available commands
• Esc twice or Ctrl+T – View transcript (reasoning and tool usage)
• Ctrl+C or type exit – Exit Codex

Example Prompts

Try these to get started:

"Create a simple Express.js API with three endpoints"

"Add TypeScript configuration to this project"

"Write unit tests for the authentication module"

"Refactor this React component to use hooks"

"Set up ESLint and Prettier for this project"

"Create a README with installation instructions"

Non-Interactive Mode

For scripting and CI/CD:

# Run a single task
codex exec "Add error handling to all API routes"

# With custom workspace
codex exec --cwd C:\Projects\myapp "Run tests and fix failures"

# YOLO mode (no confirmations - use with caution!)
codex exec --yolo "Update all dependencies"

---

Windows-Specific Features

Windows Sandbox

When running natively on Windows, Codex implements an experimental sandbox:

• Restricts file writes to your working folder
• Blocks network access by default
• Scans for world-writable directories

Recommendations:

• Remove write access from world-writable folders when prompted
• Use WSL2 for better sandboxing capabilities
• Always review changes before accepting

PowerShell Integration

Codex works seamlessly in PowerShell:

# Set execution policy for scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Create alias for easier access
Set-Alias cx codex

# Add to PowerShell profile for persistence
Add-Content -Path $PROFILE -Value "Set-Alias cx codex"

Windows Terminal Integration

For the best experience, use Windows Terminal:

1. Install from Microsoft Store
2. Set Ubuntu (WSL) as default profile (if using WSL)
3. Customize appearance for better readability

---

VS Code Integration

Codex has excellent VS Code integration for both WSL and native Windows.

Install VS Code Extension

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for “Codex”
4. Click “Install”

Using Codex with WSL in VS Code

1. Install the “WSL” extension in VS Code
2. Open a WSL terminal in VS Code: # From WSL terminalcd ~/code/your-projectcode .
3. VS Code opens in WSL mode (look for green “WSL: Ubuntu” in bottom-left)
4. Integrated terminal automatically uses WSL

Configuration

The Codex extension appears in the sidebar:

• Agent Mode: Lets Codex read, write, and execute
• Chat Mode: Conversational assistance without file changes
• Model Selection: Dropdown to choose GPT-5.2-Codex or other models

---

Updating Codex

Check Current Version

# Check installed version
codex --version

# Check latest available version
npx -y @openai/codex@latest --version

Update via npm

In WSL or PowerShell:

# Clear npm cache
npm cache clean --force

# Update to latest version
npm install -g @openai/codex@latest

# Verify update
codex --version

Update via Built-in Command

# Use Codex's upgrade command
codex --upgrade

Troubleshooting Updates

If the version doesn’t update:

In PowerShell:

# Find all Codex installations
Get-Command codex -All | Select-Object -Expand Source

# Remove old versions
npm uninstall -g @openai/codex

# Reinstall fresh
npm install -g @openai/codex@latest

# Open NEW PowerShell window
# Verify version
codex --version

In WSL:

# Find all Codex installations
which -a codex

# Check npm global installations
npm ls -g @openai/codex --depth=0

# Remove old versions
npm uninstall -g @openai/codex

# Reinstall fresh
npm install -g @openai/codex@latest

# Open new terminal
# Verify version
codex --version

---

Security Considerations

Git Version Control

Always use Git when working with Codex:

# Before running Codex
git add .
git commit -m "Before Codex changes"

# After Codex completes
git diff  # Review changes
git add .  # Stage if satisfied
git commit -m "After Codex: [description]"

# Or revert if needed
git reset --hard HEAD

Execution Policies

Configure what Codex can do without approval:

# In config.toml

[execution]

approval_mode = “on-request” # Recommended # Allowed commands without approval allowed_commands = [ “npm install”, “npm test”, “git status” ]

Environment Variables

Never hardcode API keys in config files:

# Use environment variables
export OPENAI_API_KEY="your-key"

# Or use a .env file (add to .gitignore)
echo "OPENAI_API_KEY=your-key" > .env
echo ".env" >> .gitignore

Windows Defender

If Codex is blocked by Windows Defender:

1. Open Windows Security
2. Go to Virus & threat protection
3. Manage settings
4. Add exclusion for Codex directory

Network Security

# Restrict internet access

[internet]

enabled = true allowed_domains = [ “pypi.org”, “npmjs.com”, “github.com” ] allowed_methods = [“GET”] # No POST, PUT, DELETE

---

Troubleshooting

Issue 1: “codex: command not found” in PowerShell

Solution:

# Check if npm global bin is in PATH
$env:PATH -split ';' | Select-String npm

# Add to PATH if missing
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable(
    "PATH",
    "$env:PATH;$npmPath",
    "User"
)

# Restart PowerShell

Issue 2: Node.js Version Too Old

Solution:

# Uninstall old Node.js
# Download latest LTS from nodejs.org
# Install fresh

# Or use nvm-windows
# Download from: github.com/coreybutler/nvm-windows

Issue 3: WSL Installation Fails

Solution:

# Enable required Windows features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart computer

# Set WSL 2 as default
wsl --set-default-version 2

# Try installation again
wsl --install

Issue 4: Permission Errors in WSL

Solution:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Reinstall Codex
npm install -g @openai/codex

Issue 5: Slow Performance in WSL

Solution:

# Work in Linux filesystem, not /mnt/c
cd ~  # Not cd /mnt/c/Users/...

# Increase WSL memory (create .wslconfig)
# In PowerShell:
@"

[wsl2]

memory=8GB processors=4 “@ | Out-File -FilePath “$env:USERPROFILE\.wslconfig” -Encoding UTF8 # Restart WSL wsl –shutdown

Issue 6: Authentication Fails

Solution:

# Remove existing credentials
# Windows:
Remove-Item -Path "$env:USERPROFILE\.codex\credentials" -Recurse -Force

# WSL:
rm -rf ~/.codex/credentials

# Try logging in again
codex login

Issue 7: Codex Hangs or Freezes

Solution:

# Kill hung process
# PowerShell:
Get-Process codex | Stop-Process -Force

# WSL:
pkill -9 codex

# Clear cache
rm -rf ~/.codex/cache

# Restart Codex
codex

---

Best Practices

1. Choose the Right Environment

• WSL2: Best for most development work
• Native Windows: For Windows-specific projects or if WSL isn’t available

2. Workspace Organization

# Good structure
~/code/
  ├── project1/
  ├── project2/
  └── experiments/

# Always cd into project before running codex
cd ~/code/project1
codex

3. Use Version Control

# Before each Codex session
git status
git add .
git commit -m "Pre-Codex checkpoint"

# After session
git diff  # Review
git commit -am "Codex: Added feature X"

4. Review Before Accepting

• Always press Esc twice to view the transcript
• Understand what Codex is doing
• Reject suspicious or unclear changes

5. Start Small

# Begin with simple prompts
"Add docstrings to all functions"
"Create a .gitignore for Node.js"

# Progress to complex tasks
"Refactor this module to use async/await"
"Implement comprehensive error handling"

6. Keep Codex Updated

# Check for updates weekly
codex --upgrade

# Or manually
npm update -g @openai/codex

7. Monitor Token Usage

# Check usage regularly
codex /status

# Optimize prompts to reduce tokens
# Be specific and concise

---

Conclusion

Codex CLI brings powerful AI-assisted development to Windows through both WSL2 and native installations. While WSL2 provides the best experience, native Windows support continues to improve.

Quick Summary

• Recommended: Install via WSL2 for stability and performance
• Alternative: Native Windows works but is experimental
• Best Practices: Use Git, review changes, and start with simple tasks
• Security: Enable sandbox mode and restrict internet access

Key Takeaways

✅ WSL2 offers the best Codex experience on Windows
✅ Native Windows support is improving but still experimental
✅ Always use version control and review AI-generated changes
✅ GPT-5.2-Codex brings improved Windows performance
✅ Regular updates ensure access to latest features

Next Steps

1. Install Codex using your preferred method
2. Complete authentication setup
3. Try simple prompts to familiarize yourself
4. Explore advanced features like code review
5. Integrate with VS Code for enhanced workflow

Resources

• Official Codex CLI Documentation
• Windows Setup Guide
• Codex Changelog
• GitHub Repository
• VS Code WSL Tutorial

Happy coding with Codex on Windows!