How to Install PI Desktop on Windows: NSIS Installer and Portable Setup Guide

You can install PI Desktop on Windows using either the NSIS installer (PI-Desktop-Setup-*.exe) for system integration and automatic updates, or the portable executable (PI-Desktop-Portable-*.exe) for zero-installation deployment without administrator rights.

PI Desktop is an open-source desktop application built on Electron and Rust that provides two distinct distribution methods for Windows users. According to the scripts/release.mjs build script in the vastsa/PI-Desktop repository, both the traditional installer and portable builds are generated from the same source code, sharing identical runtime architectures while serving different deployment scenarios.

Prerequisites for Installing PI Desktop on Windows

Before you install PI Desktop on Windows, ensure Git for Windows is installed and available on your system PATH. The application relies on bash.exe provided by Git for its cross-platform shell strategy, as documented in ADR D084. This dependency is required for plugins that execute bash commands on Windows, since the installer does not bundle a shell environment.

Downloading the Windows Binaries

The vastsa/PI-Desktop repository publishes Windows artifacts on the releases page. As shown in the asset matrix at line 312 of README.md and defined in scripts/release.mjs, the release pipeline generates two x64 binaries:

• NSIS Installer: PI-Desktop-Setup-<VERSION>.exe (recommended for most users)
• Portable Executable: PI-Desktop-Portable-<VERSION>.exe (for restricted environments)

You can download these manually from the browser, or use automated scripts to fetch the latest version:

# PowerShell: Download the NSIS installer (replace VERSION with the latest tag)

$version = "0.14.6"
$url = "https://github.com/vastsa/PI-Desktop/releases/download/v$version/PI-Desktop-Setup-$version.exe"
Invoke-WebRequest -Uri $url -OutFile "$env:USERPROFILE\Downloads\PI-Desktop-Setup.exe"

:: CMD: Download the portable executable with curl (Windows 10+)
set VERSION=0.14.6
curl -L -o "%USERPROFILE%\Downloads\PI-Desktop-Portable-%VERSION%.exe" ^
  https://github.com/vastsa/PI-Desktop/releases/download/v%VERSION%/PI-Desktop-Portable-%VERSION%.exe

Installation Methods

Choose the method that fits your administrative constraints and update preferences. Both methods deploy the same Electron and Rust host core architecture described in docs/spec/00-baseline.md.

Method 1: Run the NSIS Installer (Recommended)

Double-click the downloaded PI-Desktop-Setup-*.exe to launch the wizard. Accept the license agreement, select an installation directory, and complete the setup. This method, detailed in docs/spec/06-delivery/06-release-runbook.md, performs three critical system integrations:

1. Writes the executable to your chosen folder and creates Start Menu shortcuts
2. Registers a Windows AppUserModelID (per ADR D141) for proper taskbar integration
3. Establishes a latest.yml feed to enable in-application automatic updates

For enterprise or silent deployment, invoke the installer with the /S flag:

# Silent installation (no GUI)

Start-Process -FilePath "$env:USERPROFILE\Downloads\PI-Desktop-Setup.exe" `
    -ArgumentList "/S" -Wait

Method 2: Deploy the Portable Executable

If you lack administrator rights or need to run PI Desktop from a USB drive, use the portable build. Simply double-click PI-Desktop-Portable-*.exe without any installation steps. As documented in docs/adr/0197-windows-portable-exe.md, this self-contained Windows x64 binary does not write files outside its container folder or modify the Windows Registry.

Important limitation: The portable build excludes the latest.yml feed mechanism found in the installed version. Consequently, you must manually download new releases from the GitHub releases page to update the application.

Verifying Your Installation

After launching PI Desktop, confirm the installation succeeded by navigating to Settings → Model configuration. Successful loading of this interface verifies that the bundled Electron runtime and Rust host core initialized correctly, as specified in the baseline architecture.

Additionally, verify your shell environment supports the cross-platform plugin system:

# Verify bash is available for plugin compatibility

bash -c 'echo "Bash version: $BASH_VERSION"'

Summary

• Two Windows binaries exist: The NSIS installer (PI-Desktop-Setup-*.exe) and the portable executable (PI-Desktop-Portable-*.exe), both generated by scripts/release.mjs from the same source tree.
• NSIS installer provides system integration via AppUserModelID registration, Start Menu shortcuts, and automatic updates through the latest.yml feed, but requires administrator privileges.
• Portable executable requires no installation, leaves no registry traces, and runs in user space, though it mandates manual updates per ADR 0197.
• Git for Windows is a mandatory prerequisite to supply bash.exe for the application's cross-platform shell strategy (ADR D084).
• Verification involves opening Settings → Model configuration to confirm the Electron and Rust stack loaded properly.

Frequently Asked Questions

What's the difference between the NSIS installer and the portable version?

The NSIS installer registers an AppUserModelID with Windows, creates Start Menu shortcuts, and establishes an update feed for automatic version management. The portable version is a self-contained executable that writes nothing to the registry or system directories, making it ideal for temporary use or restricted machines, but you must manually download new releases to update.

Does PI Desktop require administrator privileges to install?

Only the NSIS installer requires elevation to write to Program Files and register system integrations. The portable executable runs entirely in user space without administrator rights, though you still need standard user permissions to execute files from your Downloads folder.

How do I update PI Desktop on Windows?

If you installed via the NSIS installer, the application checks the latest.yml feed published to GitHub Releases and can update automatically within the app. If you use the portable version, you must manually download the new PI-Desktop-Portable-*.exe from the releases page and replace your existing file, as the portable build intentionally excludes the automatic updater to maintain its zero-footprint design.

Why do I need Git for Windows installed?

PI Desktop uses bash.exe from Git for Windows to execute its cross-platform shell strategy, as specified in ADR D084. This allows plugins to run bash commands consistently across operating systems. The installer does not bundle bash, so installing Git for Windows satisfies this runtime dependency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}