Skip to main content

​
Prerequisites

Before building PowerToys, ensure your development environment meets these requirements:

​
System Requirements

  • Windows 10 April 2018 Update (version 1803) or newer
  • Long paths enabled in Windows (see instructions)
  • Windows Developer Mode enabled

​
Required Software

Visual Studio 2022 17.4+ or Visual Studio 2026 with the following workloads:
  • Desktop Development with C++
  • WinUI application development
  • .NET desktop development
  • Windows 10 SDK (10.0.22621.0)
  • Windows 11 SDK (10.0.26100.3916)
Additional Components:
  • .NET 8 SDK
  • Git (for cloning and submodule management)
You can automatically install Visual Studio with all required components using WinGet configuration files:
winget configure .config\configuration.vsEnterprise.winget
Choose the file matching your Visual Studio edition (Professional, Enterprise, etc.).

​
Initial Setup

Run the automated setup script from the repository root: 
.\tools\build\setup-dev-environment.ps1
This script will:
  • Enable Windows long path support (requires administrator privileges)
  • Enable Windows Developer Mode (requires administrator privileges)
  • Guide you through installing required Visual Studio components from .vsconfig
  • Initialize git submodules
Run with -Help to see all available options.

​
Manual Setup

If you prefer manual setup:
  1. Import Visual Studio components:
    • Open Visual Studio Installer
    • Import the .vsconfig file from the repository root
    • Or open PowerToys.slnx and click “install extra components” if prompted
  2. Initialize submodules: 
    git submodule update --init --recursive
Submodule initialization is a one-time step required before you can compile most parts of PowerToys. Failure to initialize submodules will result in build errors.

​
Build Methods

​
Building with Visual Studio

  1. Open PowerToys.slnx in Visual Studio
  2. Select configuration from the Solutions Configuration dropdown:
    • Debug - For development and debugging
    • Release - For production builds
  3. Build the solution:
    • Menu: Build > Build Solution
    • Keyboard: Ctrl+Shift+B
Build output will be located in:
  • x64\Release\ for Release builds
  • x64\Debug\ for Debug builds
You can run x64\Release\PowerToys.exe directly without installing, but some modules (PowerRename, ImageResizer, File Explorer extensions) require building and installing the full installer to function properly.

​
Building from Command Line

PowerToys provides several build scripts in tools\build\ for command-line builds:

​
Quick Build (Essentials)

For faster iteration during development, build only the runner and settings: 
# Using PowerShell script
.\tools\build\build-essentials.ps1

# Or using CMD wrapper
.\tools\build\build-essentials.cmd
Options: 
# Specify platform and configuration
.\tools\build\build-essentials.ps1 -Platform x64 -Configuration Release

# ARM64 build
.\tools\build\build-essentials.ps1 -Platform arm64 -Configuration Debug

​
Full Solution Build

Build any projects in the current directory: 
# Auto-detects platform
.\tools\build\build.ps1

# Specify configuration
.\tools\build\build.ps1 -Platform x64 -Configuration Release

# Restore packages only
.\tools\build\build.ps1 -RestoreOnly

# Pass additional MSBuild arguments
.\tools\build\build.ps1 '/p:CIBuild=true' '/p:CustomProp=Value'

​
Build with Installer

To build the complete installer package (Release only): 
.\tools\build\build-installer.ps1 -Platform x64 -Configuration Release
Installer Options: 
# Per-user installer
.\tools\build\build-installer.ps1 -PerUser true

# Specify installer suffix
.\tools\build\build-installer.ps1 -InstallerSuffix wix5
The installer can only be built in Release mode. Debug installers are not supported.

​
Using MSBuild Directly

For advanced scenarios, use MSBuild directly from Developer Command Prompt: 
# Full build with restore
msbuild -restore -p:RestorePackagesConfig=true -p:Platform=x64 -m PowerToys.slnx

# ARM64 build
msbuild -restore -p:RestorePackagesConfig=true -p:Platform=ARM64 -m PowerToys.slnx /tl /p:NuGetInteractive="true"

# Clean build
msbuild PowerToys.slnx /t:Clean /p:Platform=x64 /p:Configuration=Debug

​
Build Configurations

​
Debug vs Release

ConfigurationUse CaseOptimizationsDebug InfoPerformance
DebugDevelopment, debuggingDisabledFullSlower
ReleaseProduction, installerEnabledMinimalOptimized

​
Platform Options

  • x64 - Intel/AMD 64-bit processors (most common)
  • ARM64 - ARM-based Windows devices
The build scripts auto-detect your platform if not specified. Override with -Platform parameter when needed.

​
Build Logs and Output

Build logs are created next to the solution/project being built:
Log FileContents
build.<config>.<platform>.errors.logErrors only (check this first)
build.<config>.<platform>.warnings.logWarnings only
build.<config>.<platform>.all.logComplete build output
build.<config>.<platform>.trace.binlogBinary log for MSBuild Structured Log Viewer
Example locations: 
build.Release.x64.errors.log
build.Debug.ARM64.all.log
build.Release.x64.trace.binlog
Use MSBuild Structured Log Viewer to analyze .binlog files for detailed build investigation.

​
Common Build Errors

​
Submodules Not Initialized

Error: Missing dependencies or file not found errors Solution: 
git submodule update --init --recursive

​
Missing NuGet Packages

Error: NuGet package restore failures Solution: 
# Run essentials build first to restore packages
.\tools\build\build-essentials.cmd

​
Missing Image Files or Assets

Error: Build errors about missing .png, .ico, or other asset files Solution: Clean and rebuild 
# Using the cleanup script
.\tools\build\clean-artifacts.ps1

# Then rebuild
.\tools\build\build.ps1
Or manually: 
# Clean via MSBuild
msbuild PowerToys.slnx /t:Clean /p:Platform=x64 /p:Configuration=Debug

# Delete build folders
Remove-Item -Recurse -Force x64, ARM64, Debug, Release, packages -ErrorAction SilentlyContinue

# Rebuild
msbuild -restore -p:Platform=x64 -m PowerToys.slnx

​
Visual Studio Environment Not Found

Error: Cannot find Visual Studio or MSBuild Solution:
  • Ensure Visual Studio is installed with required workloads
  • Run from “Developer PowerShell for VS 2022” or “Developer Command Prompt for VS”
  • Verify vswhere.exe exists in C:\Program Files (x86)\Microsoft Visual Studio\Installer

​
Long Path Issues

Error: File path too long errors Solution: Enable long paths in Windows: 
# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Or use the automated setup script which handles this for you.

​
Unsigned DLLs/Executables

Error: Pipeline fails with unsigned DLL/executable errors Solution:
  • For PowerToys modules: Add them to the signing configuration
  • For external libraries: Verify they’re safe before adding to signing list
  • Check the signing JSON file in the repository

​
Build Performance Tips

​
Faster Iteration

  1. Use essentials build for quick testing of runner and settings: 
    .\tools\build\build-essentials.ps1
  2. Build specific projects by navigating to the project folder: 
    cd src\modules\YourModule
..\..\..\tools\build\build.ps1
  3. Parallel builds with MSBuild -m flag: 
    msbuild -m -p:Platform=x64 PowerToys.slnx

​
Reduce Disk Usage

Clean build artifacts periodically: 
# Clean using helper script
.\tools\build\clean-artifacts.ps1

# Skip MSBuild clean, only delete folders
.\tools\build\clean-artifacts.ps1 -SkipMSBuildClean

​
Building Individual Components

​
Building a Specific Module

# Navigate to module directory
cd src\modules\FancyZones

# Build the module
..\..\..\tools\build\build.ps1

​
Building the Installer Only

Prerequisites:
  1. Build PowerToys.slnx in Release mode
  2. Build tools\BugReportTool\BugReportTool.sln
  3. Build tools\StylesReportTool\StylesReportTool.sln
Then: 
# Build installer
cd installer
..\tools\build\build.ps1 -Configuration Release
Or use the all-in-one script: 
.\tools\build\build-installer.ps1

​
Git Worktree Workflow

For working on multiple features simultaneously, use git worktrees: 
# Create worktree from branch
.\tools\build\New-WorktreeFromBranch.ps1

# Create worktree from fork
.\tools\build\New-WorktreeFromFork.ps1

# Create worktree from issue
.\tools\build\New-WorktreeFromIssue.ps1

# Delete worktree
.\tools\build\Delete-Worktree.ps1
See tools\build\Worktree-Guidelines.md for detailed instructions.

​
Next Steps

Debugging

Learn how to debug PowerToys modules and troubleshoot issues

Testing

Write and run tests for your PowerToys contributions

Creating New Utility

Step-by-step guide to create a new PowerToys utility

Coding Style

Follow PowerToys coding standards and conventions

Build docs developers (and LLMs) love

Get started for freeTalk to us