This page is the entry point for contributors and developers working on the PowerToys codebase. It covers environment prerequisites, the setup script, build methods, and the overall developer workflow. For step-by-step build instructions, see Building from Source. For a detailed breakdown of the repository's directory layout, see Project Structure. To learn how to add a new module, see Creating a New Module.
The following tools are required before building PowerToys:
| Requirement | Version | Notes |
|---|---|---|
| Windows | 10 version 1803+ | Build 17134 or later |
| Visual Studio | 2026 (recommended) or 2022 17.4+ | See workloads below |
| .NET SDK | 8 | Required for C# managed projects |
| Windows 10 SDK | 10.0.22621.0 | Via VS Installer |
| Windows 11 SDK | 10.0.26100.3916 | Via VS Installer |
| Long paths enabled | โ | Registry or script |
| Developer Mode | โ | Required for package registration |
Required Visual Studio workloads:
The repository's `.vsconfig` file at the repo root lists all required components and can be imported directly by the VS Installer.
Sources: doc/devdocs/readme.md1-61
The recommended path for new contributors is the setup script:
The script performs four steps:
| Step | Action | Elevation Required |
|---|---|---|
| 1 | Enable Windows long path support (LongPathsEnabled registry key) | Yes |
| 2 | Enable Windows Developer Mode | Yes |
| 3 | Guide installation of required VS workloads from .vsconfig | Yes (VS Installer) |
| 4 | Initialize git submodules (git submodule update --init --recursive) | No |
The script is idempotent and safe to run multiple times. It accepts flags to skip individual steps:
Sources: tools/build/setup-dev-environment.ps11-294
The .config/ folder contains WinGet DSC configuration files that automate Visual Studio installation:
| File | Edition |
|---|---|
.config/configuration.winget | Community |
.config/configuration.vsProfessional.winget | Professional |
.config/configuration.vsEnterprise.winget | Enterprise |
Each file enables Developer Mode, installs Visual Studio, and wires in the .vsconfig workload list.
Sources: .config/configuration.winget1-40 .config/configuration.vsEnterprise.winget1-40 .config/configuration.vsProfessional.winget1-40
Setup sequence diagram โ from clone to running binary
Sources: doc/devdocs/readme.md26-90 tools/build/setup-dev-environment.ps1256-294
PowerToys.slnx in Visual Studio.Debug or Release in the Solution Configuration dropdown.Ctrl+Shift+B).Output lands in x64\Release\ or x64\Debug\ depending on configuration. PowerToys.exe can be launched directly from there without installing.
Note: Shell extension modules (PowerRename, ImageResizer, File Explorer add-ons) require a full installer build to be available at runtime.
Scripts live under tools\build\:
| Script | Purpose |
|---|---|
build.ps1 | Full solution build, auto-detects platform |
build.ps1 -Platform x64 -Configuration Release | Explicit platform/config |
build-essentials.ps1 | Runner + Settings only (faster iteration) |
build-installer.ps1 | Full build including installer (Release only) |
clean-artifacts.ps1 | Removes build output folders and runs MSBuild Clean |
Sources: doc/devdocs/readme.md63-90 doc/devdocs/development/dev-with-vscode.md63-77
Key solution files and how they relate to each other
Sources: doc/devdocs/readme.md165-178 doc/devdocs/core/installer.md1-30
The installer is a two-part build: an EXE bootstrapper wrapping an MSI. It can only be compiled in Release mode. Prerequisites:
PowerToys.slnx (Release)tools\BugReportTool\BugReportTool.sln (Release)tools\StylesReportTool\StylesReportTool.sln (Release)installer\PowerToysSetup.slnx (Release)One-stop script:
For more details on the WiX structure, custom actions, and per-user vs. machine-wide packaging, see Installer Architecture.
Sources: doc/devdocs/readme.md165-178 doc/devdocs/core/installer.md88-156
Key principle: Follow the patterns already established in the codebase.
| Guideline | Summary |
|---|---|
| Coding style | See doc/devdocs/development/style.md |
| Development best practices | See doc/devdocs/development/guidelines.md |
| Logging and telemetry | See doc/devdocs/development/logging.md |
| Localization | See doc/devdocs/development/localization.md |
| UI testing | See doc/devdocs/development/ui-tests.md |
| VS Code workflow | See doc/devdocs/development/dev-with-vscode.md |
Module isolation rules:
src/modules/<YourModule>/.src/common/ instead of creating cross-module dependencies.Sources: doc/devdocs/readme.md103-119
Key workflow rules:
Squash and merge by default; use Rebase and merge only when logically separate commits must be preserved.Sources: doc/devdocs/readme.md120-131
The following diagram shows how the developer-facing docs files relate to the subsections of this guide.
Sources: doc/devdocs/readme.md103-163
| Page | Purpose |
|---|---|
| Building from Source | Clone, prerequisites, setup script, Visual Studio and CLI build steps |
| Project Structure | Top-level directory layout, solution files, Directory.Build.props |
| Creating a New Module | PowertoyModuleIface, runner registration, settings pages, GPO, localization |
| Creating PowerToys Run Plugins | IPlugin interface, plugin metadata, result types, install path |
| Creating Command Palette Extensions | ICommandProvider, IListItem, packaging, extension discovery |
| Debugging and Testing | Attaching to runner/module processes, debug builds, unit and UI tests |
| Code Quality and CI | XAML styling, NuGet checks, ARM64 config, CI pipeline gates |
| Spell Check System | Allow lists, expect lists, GitHub Action configuration |
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.