Install Codex CLI on Windows 2026

Three Ways to Install Codex CLI on Windows

Choose the method that best fits your development setup:

Method 1: WSL2 (Recommended)

WSL2 runs a full Linux kernel inside Windows, giving the best Node.js toolchain compatibility with the fewest permission problems. If you already use WSL2 for development, this is the obvious choice.

Prerequisites: If WSL2 is not installed, run this in an Administrator PowerShell:

PS> wsl --install
# Restart Windows when prompted. Ubuntu is installed by default.

Open WSL2 (Ubuntu), then install Node.js 18+ via nvm and Codex CLI:

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

# Reopen terminal, then install Node 22
$ nvm install 22 && nvm use 22
$ node -v   # v22.x.x

# Install Codex CLI
$ npm install -g @openai/codex

# Verify
$ codex --version

Method 2: PowerShell + Node.js for Windows

Install Codex CLI natively on Windows without WSL2, using a standard Windows Node.js installation.

Step 1: Install Node.js LTS from nodejs.org, or use winget:

# Install Node.js LTS via winget (recommended)
PS> winget install OpenJS.NodeJS.LTS

# Reopen PowerShell and verify
PS> node -v   # v22.x.x or higher

Step 2: Install Codex CLI:

PS> npm install -g @openai/codex
PS> codex --version

Method 3: Git Bash / Scoop

If you use Git Bash (included with Git for Windows) or the Scoop package manager:

# Install Node.js via Scoop
> scoop install nodejs-lts

# Install Codex CLI
> npm install -g @openai/codex
> codex --version

Git Bash is a MSYS2 environment that behaves like a Linux shell. Most bash-compatible commands work, but note that Git Bash uses Linux-style paths (/c/Users/...) which can occasionally cause issues with Windows-native tools.

Windows-Specific Proxy Configuration

Proxy configuration is the most common obstacle for Windows users. The approach differs by installation method:

PowerShell Proxy Setup

Node.js on Windows does not automatically pick up the Windows system proxy. You need to set environment variables explicitly:

# Assuming local proxy on port 7890 (Clash default)
PS> $env:HTTPS_PROXY = "http://127.0.0.1:7890"
PS> $env:HTTP_PROXY  = "http://127.0.0.1:7890"

# Test that the proxy works
PS> codex "Hello, test connection"

To make the proxy setting permanent, add it to your PowerShell profile:

# Open your PowerShell profile (created automatically if missing)
PS> notepad $PROFILE

# Add these lines at the end of the file:
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY  = "http://127.0.0.1:7890"

Clash / V2Ray Configuration

When using Clash for Windows or V2RayN, verify these settings:

• Enable "Allow LAN" mode — required so other processes (including WSL2) can connect through 127.0.0.1
• Confirm the HTTP/HTTPS proxy port (Clash default: 7890, V2RayN default: 10809)
• System proxy mode in Clash only sets IE/WinHTTP proxy — Node.js processes still need $env:HTTPS_PROXY set explicitly

WSL2 Proxy Passthrough (Most Common Issue)

WSL2 uses a virtual network adapter with its own IP, communicating with Windows via NAT. This means:

• Windows system proxy settings are completely invisible to processes inside WSL2
• Even with Clash/V2Ray running on Windows, Codex cannot reach OpenAI from inside WSL2 without additional configuration
• You must point HTTPS_PROXY inside WSL2 at the Windows host IP

Option A: Use the Windows Host IP (Recommended)

WSL2's default gateway (the Windows host IP in the WSL2 network) can be read from /etc/resolv.conf:

# Get the Windows host IP
$ cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
# Typically outputs something like 172.x.x.1

# One-liner to set proxy (replace 7890 with your actual proxy port)
$ export HTTPS_PROXY=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):7890
$ export HTTP_PROXY=$HTTPS_PROXY

# Test connectivity
$ curl -I https://api.openai.com

Add these exports to ~/.bashrc or ~/.zshrc for persistence:

$ cat >> ~/.bashrc <<'EOF'
# Codex CLI / WSL2 proxy configuration
export HTTPS_PROXY=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):7890
export HTTP_PROXY=$HTTPS_PROXY
export NO_PROXY=localhost,127.0.0.1
EOF
$ source ~/.bashrc

Option B: Use proxychains

If you prefer not to modify global environment variables, use proxychains-ng for per-command proxy routing:

# Install proxychains-ng
$ sudo apt install proxychains4

# Edit the config (change the last line to your proxy)
$ sudo nano /etc/proxychains4.conf
# Change the last line to:
# http 172.x.x.1 7890

# Run codex through proxychains
$ proxychains4 codex "create a hello.js that prints Hello World"

PowerShell Script Execution Policy

Windows restricts PowerShell script execution by default. You may encounter this error when running codex:

codex.ps1 cannot be loaded because running scripts is disabled on this system.
File ... cannot be loaded because the execution of scripts is disabled...

Fix: Set the execution policy for the current user (no Administrator required):

PS> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# Enter Y to confirm

# Verify the policy was applied
PS> Get-ExecutionPolicy -Scope CurrentUser
# RemoteSigned

RemoteSigned allows locally-created scripts and remotely-downloaded scripts that are signed by a trusted publisher. This is the recommended balance between security and usability. Avoid using Unrestricted or Bypass.

Common Windows Errors

EPERM: operation not permitted

Symptom: EPERM: operation not permitted, mkdir ... during npm install or when running codex.

Causes and fixes:

• npm global directory permissions: Avoid using npm install -g as Administrator. Use nvm-windows to manage Node — nvm stores global packages in your user directory, avoiding permission issues
• Antivirus interference: Windows Defender or third-party antivirus may block npm package extraction. Temporarily disable real-time protection or add the npm cache directory (%APPDATA%\npm-cache) as an exclusion
• WSL2 filesystem: Do not place projects in /mnt/c/... (Windows filesystem). Put them in ~/ (WSL2 Linux filesystem) for better performance and permissions

# Download nvm-windows from github.com/coreybutler/nvm-windows/releases
# After installation, in a regular (non-admin) PowerShell:
PS> nvm install 22
PS> nvm use 22
PS> npm install -g @openai/codex

'node' is not recognized

Symptom: 'node' is not recognized as an internal or external command

Cause: Node.js installation directory is not in the PATH environment variable.

Fix:

1. Reinstall Node using winget: winget install OpenJS.NodeJS.LTS — the installer automatically adds it to PATH
2. Or manually add Node's install directory (typically C:\Program Files\nodejs) to PATH via System Properties → Environment Variables
3. Reopen PowerShell after modifying PATH — changes don't apply to the current session

SSL Certificate Errors (Corporate Networks)

Symptom: UNABLE_TO_VERIFY_LEAF_SIGNATURE or SELF_SIGNED_CERT_IN_CHAIN

Cause: Corporate SSL inspection replaces OpenAI's certificate with a company-signed one that Node.js doesn't trust.

Fix: Ask IT for the corporate root CA certificate (.crt or .pem), then:

# Method 1: point Node to extra CA certs via environment variable
PS> $env:NODE_EXTRA_CA_CERTS = "C:\path\to\company-root-ca.pem"

# Method 2: configure npm to use corporate CA file
PS> npm config set cafile "C:\path\to\company-root-ca.pem"

Verify the Installation

After installing and configuring your proxy, verify everything works end-to-end:

1. Check the version:
   TerminalCopy

   $ codex --version
   # Prints a version number (e.g. 0.1.x) — installation succeeded

2. Send a simple command to test connectivity:
   TerminalCopy

   $ codex "Create a hello.js that prints Hello from Codex!"
   # Codex will ask for confirmation, then create the file

3. Run the generated file:
   TerminalCopy

   $ node hello.js
   # Hello from Codex!

FAQ