Set up Windows for Codex

Before you start

This guide uses Windows 11 and PowerShell 7. Work through steps 1–4 in order. If a tool is already installed, use its version check and skip the installation. You only need one way to use Codex and the tools required by your project.

How to use the commands: Paste each command into the terminal and press Enter. Wait for it to finish before running the next one. Lines starting with # are explanations; you can leave them in when copying a block.

1. Set up PowerShell 7 and Windows Terminal

Open the Start menu, search for Windows PowerShell, and open it. Use this existing shell to install PowerShell 7 and Windows Terminal with winget, the Windows package manager.

# Install modern Windows Terminal and PowerShell 7
winget install --id Microsoft.WindowsTerminal -e
winget install --id Microsoft.PowerShell -e

# After installation, close and reopen the terminal.
# Check that PowerShell 7 is installed:
pwsh --version
# Expected: PowerShell 7.x.x

If winget is not recognized, install or update App Installer in the Microsoft Store, then reopen PowerShell. See Microsoft’s PowerShell installation guide for other installation options.

1. Open Windows Terminal from the Start menu.
2. Open the arrow menu beside the tabs and choose Settings → Startup. Set the default profile to PowerShell (the new PowerShell 7 installation), then save.
3. Open a new tab and run $PSVersionTable.PSVersion. The Major value should be 7. Use this tab for the rest of the guide.

Only if scripts are blocked: If PowerShell says “running scripts is disabled,” the setting below allows local scripts for your Windows account. Scripts marked as downloaded from the internet still need a trusted signature unless you explicitly unblock them. Run it in PowerShell 7 and confirm with Y if prompted. On a managed work computer, your organization’s policy may take priority. Read about execution policies.

# Allows local scripts to run while requiring signatures for remote downloads
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. Install and set up Git

Git keeps a history of your project. Start by running git --version in PowerShell 7. If Git is missing, run winget install --id Git.Git -e, follow the installer prompts, then close and reopen Windows Terminal. Run git --version again; it should print a version number.

The settings below apply to all repositories for your Windows account. They are useful defaults for new projects; follow your team’s instructions if you already have a development setup. LF and CRLF are two ways of marking the end of a line in a text file. Keeping line endings consistent makes code changes easier to review.

# Store text with LF line endings; leave checkouts as stored
git config --global core.autocrlf input

# Enable long path support in Git (other tools may still have limits)
git config --global core.longpaths true

# Set default branch name to main
git config --global init.defaultBranch main

Before your first commit, set the name and email that should appear in your Git history. Replace the example values with your own; you can use your Git hosting provider’s private commit email.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Check your saved settings
git config --global --list

Check before changing an existing project: A .gitattributes file can define its own line-ending rules. Keep those rules and any existing sign-in configuration. In VS Code, use the status bar to check that files use UTF-8 and the line endings your project expects. Git’s configuration reference explains these settings.

3. Choose how you want to use Codex

Choose the option that suits how you like to work. VS Code is a useful starting point if you want to see your files and review edits in the same window. You can also use Codex in the desktop app or from a terminal.

Check it works: Ask Codex: “Read this project and explain what it does. Tell me how to run it and its tests. Do not change any files yet.” A useful response should refer to files in the folder you opened.

If Codex asks you to set up its Windows sandbox, follow the setup prompts. The sandbox controls which files and commands Codex can access. You can use Codex natively on Windows; WSL is optional for projects that need a Linux environment. See OpenAI’s Windows setup guidance for help.

4. Install the tools your project needs

A runtime runs your code, and a toolchain includes the tools used to build and test it. Check your project’s README for the required tools and versions. You do not need to install every language below; a basic HTML and CSS project may only need a browser.

# JavaScript or TypeScript projects
node --version
npm --version

# Python projects
py --version

# Rust projects
rustc --version
cargo --version

# C# or .NET projects
dotnet --list-sdks

# PHP projects
php --version
composer --version

If a required command is missing, install the version listed in your project’s README. Use the official installer for that language. For Node.js, choose the LTS release if the project does not specify a version; if it uses a version manager such as fnm, follow the project’s setup instructions.

After installing: Close and reopen Windows Terminal, your editor, and Codex, then repeat the relevant version check. This lets them pick up changes to PATH, the list of folders Windows searches for commands.

You’re ready when: PowerShell and Git report their versions, Codex can read the correct project folder, and the required project tools are available. Next, follow the README to install dependencies and run the project’s existing tests.

Fix common Windows problems