This page covers how to clone the PowerToys repository, install prerequisites, run the automated environment setup, and build the solution using either Visual Studio or command-line scripts. It is focused on local developer builds.
For information about the CI/CD pipeline and how release artifacts are produced, see Build and Deployment Pipeline. For debugging techniques after a successful build, see Debugging and Testing. For the repository's directory layout, see Project Structure.
The following must be in place before building.
| Requirement | Details |
|---|---|
| OS | Windows 10 version 1803 (April 2018 Update) or newer |
| Visual Studio | Visual Studio 2026 (recommended) or Visual Studio 2022 17.4+ |
| VS Workloads | Desktop Development with C++; WinUI application development; .NET desktop development |
| Windows SDK | 10.0.22621.0 and 10.0.26100.3916 |
| .NET SDK | .NET 8 SDK (minimum); .NET 6 and .NET 9 are also used in parts of the build |
| Windows long paths | Must be enabled in the registry |
| Windows Developer Mode | Required for certain package operations |
The exact set of required Visual Studio components is tracked in the .vsconfig file at the repository root. Visual Studio Installer can import this file directly to install the correct workloads.
Sources: doc/devdocs/readme.md8-17
WinGet configuration files in .config/ can install Visual Studio and required workloads in a single step:
winget configure .config\configuration.winget
Variant files exist for each VS edition:
| File | Edition |
|---|---|
.config/configuration.winget | Community |
.config/configuration.vsProfessional.winget | Professional |
.config/configuration.vsEnterprise.winget | Enterprise |
Each file installs the matching Visual Studio edition, then imports the .vsconfig workload file and enables Developer Mode.
After Visual Studio is installed, run the automated setup script from the repository root:
Sources: doc/devdocs/readme.md19-41 tools/build/setup-dev-environment.ps11-50 .config/configuration.winget1-39
setup-dev-environment.ps1 DoesSetup script: tools\build\setup-dev-environment.ps1
Sources: tools/build/setup-dev-environment.ps11-50 doc/devdocs/readme.md28-60
The script accepts several flags:
| Flag | Effect |
|---|---|
-SkipLongPaths | Skip enabling long path registry key |
-SkipDevMode | Skip enabling Developer Mode |
-SkipVSComponents | Skip Visual Studio workload installation |
-SkipSubmodules | Skip git submodule update |
-VSInstallPath <path> | Override auto-detection of the VS install directory |
-Help | Print usage |
If you prefer not to use the script:
Enable Windows long paths via Group Policy or the registry key HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1.
Open PowerToys.slnx in Visual Studio. If a prompt appears to install extra components, click Install.
Alternatively, open Visual Studio Installer, select Modify on your installation, and import .vsconfig from the repository root.
Initialize git submodules:
git submodule update --init --recursive
Sources: doc/devdocs/readme.md43-61
PowerToys uses multiple solution files for different build targets:
| Solution File | Purpose |
|---|---|
PowerToys.slnx | Main solution โ all modules, runner, settings UI, tests |
installer\PowerToysSetup.slnx | Installer (MSI + bootstrapper) |
tools\BugReportTool\BugReportTool.sln | Bug report tool |
tools\StylesReportTool\StylesReportTool.sln | XAML style verification tool |
Note: The installer solution can only be compiled in
Releasemode, and requires the main solution to be compiled first.
Sources: doc/devdocs/readme.md63-76 doc/devdocs/core/installer.md23-30
PowerToys.slnx.Debug or Release.x64 or ARM64.Ctrl+Shift+B.Build output is placed under x64\Release\ (or x64\Debug\, ARM64\Release\, etc.) in the repository root.
The runner executable can be launched directly:
x64\Release\PowerToys.exe
Some modules (PowerRename, Image Resizer, File Explorer extensions) require the installer to be built and run to register shell extensions. The core runner and settings UI work without this.
Sources: doc/devdocs/readme.md64-71
Several PowerShell scripts are provided in tools\build\:
| Script | Effect |
|---|---|
tools\build\build.ps1 | Build the full solution; auto-detects platform |
tools\build\build-essentials.ps1 | Build only the runner and settings UI for faster iteration |
tools\build\build-installer.ps1 | Build everything including the installer (Release only) |
Example invocations:
You can also invoke MSBuild directly in a Developer PowerShell for VS terminal:
Sources: doc/devdocs/readme.md73-89 doc/devdocs/development/dev-with-vscode.md63-70
Supported platforms: x64, ARM64
Supported configurations: Debug, Release
The Directory.Build.props file at the repository root applies settings to all projects, including version information, analyzers, and platform targets. The RepoRoot MSBuild property is defined there and used throughout project files.
Build output layout:
Sources: Directory.Build.props1-26 doc/devdocs/readme.md69-71
The installer is built in two steps โ first the main solution, then the installer solution. All must be built in Release mode.
Installer build sequence:
Step-by-step:
PowerToys.slnx in Release mode.tools\BugReportTool\BugReportTool.sln in Release mode.tools\StylesReportTool\StylesReportTool.sln in Release mode.installer\PowerToysSetup.slnx in Release mode.The build-installer.ps1 script automates all four steps.
Sources: doc/devdocs/readme.md165-178 doc/devdocs/core/installer.md23-30
NuGet packages are restored automatically by MSBuild when using the -restore flag. The repository uses both centralized PackageReference (managed via Directory.Packages.props) and legacy packages.config for certain native projects.
Key package management files:
| File | Role |
|---|---|
Directory.Packages.props | Central version pinning for PackageReference projects |
packages.config (repo root) | MSBuildCache package versions |
nuget.config | Feed configuration |
To restore explicitly before building:
Sources: Directory.Build.props82-100 packages.config1-6
For developers who prefer VS Code, tasks.json entries and a Developer PowerShell terminal profile can be configured. A Developer PowerShell for VS terminal must be set up so that msbuild is on the path.
See doc/devdocs/development/dev-with-vscode.md for the full configuration. The general flow is identical to the command-line approach above โ run msbuild targeting PowerToys.slnx.
Sources: doc/devdocs/development/dev-with-vscode.md1-70
Sources: Directory.Build.props1-26 Directory.Build.targets1-10 tools/build/setup-dev-environment.ps11-50 .config/configuration.winget1-39
| Problem | Cause | Solution |
|---|---|---|
| Build fails with path-too-long errors | Long path support not enabled | Run setup-dev-environment.ps1 or enable manually in registry |
| Missing submodule headers | Submodules not initialized | Run git submodule update --init --recursive |
| NuGet restore fails for native projects | packages.config restore not requested | Pass -p:RestorePackagesConfig=true to MSBuild |
| Shell extension modules not working | Installer not built/run | Build PowerToysSetup.slnx and install |
| ARM64 tests do not run | No ARM64 test agents | Expected; tests only run on x64 in CI |
| VS component missing prompt at open | .vsconfig workloads not installed | Click Install in the prompt, or re-import .vsconfig via VS Installer |
Sources: doc/devdocs/readme.md8-17 Directory.Build.props28-60 doc/devdocs/development/debugging.md1-30
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.