Skip to documentation content

Run Pi on Windows

Run Pi either as a native Windows process or inside Windows Subsystem for Linux (WSL). Native Windows uses Git Bash by default for Bash commands and can optionally expose PowerShell to the model. Pi inside WSL uses the Linux environment and its Bash installation.

Follow the main Quickstart to install and authenticate Pi. Use this page to choose and configure its command environment.

Choose native Windows or WSL

EnvironmentCommand environmentUse it when
Native Windows with Git BashGit Bash for the built-in bash tool and ! commandsYour files and development tools primarily live on Windows
Native Windows with the powershell toolPowerShell for model tool calls; Bash remains available for ! commandsThe task depends on PowerShell modules or Windows-native commands
WSLLinux Bash and tools inside the selected WSL distributionYour files and toolchain already live in Linux or WSL

Use Git Bash on native Windows

For most native Windows users, installing Git for Windows is sufficient.

Pi resolves Bash in this order:

  1. shellPath from ~/.pi/agent/settings.json
  2. Git Bash at %ProgramFiles%\Git\bin\bash.exe
  3. Git Bash at %ProgramFiles(x86)%\Git\bin\bash.exe
  4. bash.exe on PATH, including Cygwin, MSYS2, or legacy WSL Bash

Start Pi and enter this command to verify the shell:

!printf 'Bash is working\n'

If Pi cannot find Bash, it reports the locations it checked. Install Git for Windows, put another Bash executable on PATH, or configure shellPath.

Let the model use PowerShell

The optional powershell tool runs commands through pwsh.exe when available, then falls back to Windows PowerShell. It starts PowerShell with -NoProfile -NonInteractive -ExecutionPolicy Bypass. Administrator-enforced execution policies can still take precedence.

PowerShell discovery checks these locations in order:

  1. pwsh.exe on PATH
  2. %ProgramFiles%\PowerShell\7\pwsh.exe
  3. powershell.exe on PATH
  4. %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe

To replace the model-facing bash tool with powershell, add this to ~/.pi/agent/settings.json:

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

["-bash", "+powershell"] does the same while keeping any other default tools you configured.

Restart Pi, then ask it to run a harmless PowerShell command. The ! and !! editor commands continue to use Bash. The powershell tool is available only when Pi runs as a native Windows process.

See Settings for other tool combinations.

WSL

WSL path conversion on Windows and extra Git branch polling in WSL recognize /mnt/<drive>, not custom mount roots.

When using the legacy WSL bash.exe launcher from Windows, Pi sends commands over stdin to avoid command-line quoting problems.

Use a custom Bash executable

Set shellPath when Bash is installed somewhere Pi does not discover automatically:

{
  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
}

JSON uses backslashes for escape sequences. When you write a Windows path with backslashes, write each backslash twice, as shown above.

See Configure shell commands for command prefixes, aliases, and the complete shell-resolution behavior.

Choose a terminal

Windows terminals run Pi through a console host (conhost). Some bundle an up-to-date copy; others use the older one built into Windows, which has bugs that affect Pi.

We recommend Windows Terminal. It always ships an up-to-date conhost, and Pi is best tested with it.

Last updated: October 2026.

TerminalConhostStatus
Windows TerminalBundled, currentRecommended
VS Code, Tabby, WezTerm nightlyBundled, currentWorks
AlacrittyBuilt-in, unless conpty.dll and OpenConsole.exe from Windows Terminal are next to alacritty.exeWorks only with those files
WezTerm 20240203 and olderBundled, oldKnown issues
Classic console (cmd.exe or PowerShell without Windows Terminal), mintty (Git Bash), ConEmu, Cmder, Hyper, Windows OpenSSHBuilt-inKnown issues

Configure Windows Terminal

Windows Terminal reserves or rewrites some modified keys. See Windows Terminal to configure Shift+Enter and Alt+Enter, and Keybindings for Pi's Windows and WSL shortcut defaults.

Known issues

These issues come from conhost. Microsoft has fixed them in its source, but has not said when the built-in conhost will get the fixes.

IssueAffectsRemedy
Switching from fullscreen to regular mode, or Ctrl+G from fullscreen, crashes the session (#9186, microsoft/terminal#17515)Built-in conhostUse a terminal with a current conhost, or start Pi with --tui-mode regular
Text such as ;0;rgb:0000/0000/0000 appears in the prompt, and BEL opens the external editor (#10256)Built-in conhost behind another terminal: mintty, Windows OpenSSHUse a terminal with a current conhost
Fragments such as 79 or 55 appear in the prompt (#10717)WezTerm 20240203Use WezTerm nightly
In regular mode, each keystroke redraws the input line on a new row (#6300)Built-in conhost, classic consoleUse fullscreen mode (the default), or a terminal with a current conhost