Microsoft PowerToys Deployment & Usage Guide

Prerequisites

For End Users

• OS: Windows 10 (version 2004 or later) or Windows 11
• Architecture: x64 or ARM64 processor
• Runtime: .NET 8 Desktop Runtime (bundled with installer)
• Privileges: Administrator rights required for machine-wide installation; standard user rights sufficient for per-user install

For Developers

• Visual Studio 2022 (17.8 or later) with the following workloads:
  • .NET desktop development
  • Desktop development with C++
  • Windows 10 SDK (10.0.22621.0) or later
• Git for Windows (2.40+)
• Windows SDK (10.0.22621.0 or later)
• NuGet CLI (latest stable)
• Windows Machine Config Validator (for GPO/testing scenarios)

Installation

Method 1: End-User Installation (Recommended)

1. Navigate to the PowerToys GitHub Releases
2. Expand Assets and download the appropriate installer:
   • PowerToysUserSetup-0.x.x-x64.exe - Per-user install (recommended for most users)
   • PowerToysSetup-0.x.x-x64.exe - Machine-wide install (requires admin)
   • PowerToysUserSetup-0.x.x-arm64.exe - For ARM64 devices
3. Run the installer and follow the setup wizard
4. Launch PowerToys from the Start Menu or system tray

Method 2: Build from Source

# Clone the repository
git clone https://github.com/microsoft/PowerToys.git
cd PowerToys

# Initialize submodules (required for dependencies)
git submodule update --init --recursive

# Restore NuGet packages
nuget restore PowerToys.sln

# Build the solution (Release configuration)
msbuild PowerToys.sln /p:Configuration=Release /p:Platform=x64 /m

Configuration

Settings Storage

PowerToys stores configuration in JSON format at:

%LocalAppData%\Microsoft\PowerToys\

Key configuration files:

• settings.json - General application settings
• MouseWithoutBorders\settings.json - Mouse Without Borders configuration
• FancyZones\zones-settings.json - FancyZones layout data

Environment Variables

For development and debugging:

# Enable verbose logging
$env:POWERTOYS_VERBOSE_LOGGING="1"

# Force portable mode (settings in executable directory)
$env:POWERTOYS_PORTABLE_MODE="1"

Group Policy (GPO) Configuration

Enterprise deployments can configure settings via GPO. The application checks:

• Registry path: HKLM\Software\Policies\PowerToys
• Supported policies: Disable specific modules, enforce update settings, configure backup paths

Build & Run

Visual Studio Development

1. Open PowerToys.sln in Visual Studio 2022
2. Set startup project to PowerToys (the main launcher)
3. Select configuration: Debug or Release
4. Platform: x64 or ARM64
5. Press F5 to build and run with debugging

Command Line Build

# Debug build
msbuild PowerToys.sln /t:Build /p:Configuration=Debug /p:Platform=x64

# Release build with packaging
msbuild PowerToys.sln /t:Build /p:Configuration=Release /p:Platform=x64 /p:PublishReadyToRun=true

# Build specific module (e.g., MouseWithoutBorders)
msbuild src\modules\MouseWithoutBorders\MouseWithoutBorders.sln /p:Configuration=Release

Running Individual Modules

During development, you can run modules independently:

# Run Settings UI
.\x64\Debug\Settings.UI\PowerToys.Settings.exe

# Run Mouse Without Borders service
.\x64\Debug\MouseWithoutBorders\MouseWithoutBorders.exe

Deployment

Creating Installers

The build system generates MSIX and MSI packages:

# Build installer packages (requires WiX Toolset v3.14+)
msbuild installer\PowerToysSetup.sln /p:Configuration=Release /p:Platform=x64

# Output location
.\installer\PowerToysSetup\x64\Release\

Silent Installation (Enterprise)

# Per-user silent install
PowerToysUserSetup-0.x.x-x64.exe --silent --no_full_ui

# Machine-wide with log
PowerToysSetup-0.x.x-x64.exe --silent --log "C:\logs\powertoys.log"

CI/CD Pipeline (GitHub Actions)

The repository includes workflows for automated builds:

• .github/workflows/ci.yml - Continuous integration
• Build artifacts: MSIX bundles, MSI installers, Portable ZIPs
• Automated code signing (requires certificates in repository secrets)

Backup and Restore Strategy

Utilize the built-in backup utility for enterprise rollouts:

// Programmatic backup (via SettingsBackupAndRestoreUtils)
var backupUtils = SettingsBackupAndRestoreUtils.Instance;
backupUtils.BackupSettings("C:\\Backups\\powertoys-backup.zip");

Troubleshooting

Installation Issues

Runtime Errors

Settings UI won't open:

• Delete %LocalAppData%\Microsoft\PowerToys\settings.json to reset
• Check Event Viewer for Application Error entries related to PowerToys.Settings.exe

Mouse Without Borders connection failures:

• Verify firewall rules allow TCP port 15100 (configurable in settings)
• Check MouseWithoutBorders\logs\ for connection diagnostics
• Ensure all machines use the same security key (configured in the Matrix settings)

High CPU/Memory usage:

• Disable specific modules via the main Settings UI
• Check PowerToys\logs\ for error loops in specific utilities

Build Errors

Missing Windows SDK:

# Install via Visual Studio Installer or:
winget install Microsoft.WindowsSDK.10.0.22621

Submodule errors:

# If MouseWithoutBorders or other modules fail to build:
git submodule foreach --recursive git clean -xfd
git submodule update --init --recursive --force

NuGet restore failures:

• Clear NuGet cache: dotnet nuget locals all --clear
• Ensure nuget.org package source is enabled in Visual Studio

Debug Logging

Enable detailed logging for support:

1. Create folder %LocalAppData%\Microsoft\PowerToys\Logs\
2. Set environment variable: $env:POWERTOYS_VERBOSE_LOGGING="1"
3. Reproduce the issue
4. Collect logs from %LocalAppData%\Microsoft\PowerToys\Logs\ and Event Viewer > Windows Logs > Application