# How to Build PowerToys with Visual Studio and build.cmd Scripts

> Easily build PowerToys from source using Visual Studio and build.cmd scripts. This guide explains how to configure your environment and use MSBuild for efficient compilation.

- Repository: [Microsoft/PowerToys](https://github.com/microsoft/PowerToys)
- Tags: how-to-guide
- Published: 2026-02-25

---

**You can build Microsoft PowerToys from source using wrapper scripts located in `tools/build/` that automatically configure the Visual Studio environment, detect your platform architecture, and invoke MSBuild with the correct parameters.**

Microsoft PowerToys is a multi-module Windows utility suite compiled from the `PowerToys.slnx` solution and dozens of supporting projects. Whether you need a fast inner-loop build or a full installer package, the repository provides **cmd wrapper scripts** that streamline building PowerToys with Visual Studio by handling environment detection, NuGet restoration, and MSBuild invocation automatically.

## Build Script Architecture Overview

The repository ships three primary cmd wrappers in `tools/build/`. Each is a thin shim that passes arguments to a corresponding PowerShell script, ensuring consistent behavior whether you launch from `cmd.exe`, PowerShell, or the Visual Studio Developer PowerShell.

### Generic Build Entry Point (`build.cmd`)

The `tools/build/build.cmd` script serves as the generic entry point for compiling any `.sln`, `.csproj`, or `.vcxproj` in the current working directory. It forwards all arguments to `tools/build/build.ps1`, which:

- Detects the host platform (`x64` or `arm64`) if not explicitly supplied.
- Bootstraps the Visual Studio developer shell via `Enter-VsDevShell` or `VsDevCmd.bat`.
- Passes extra MSBuild arguments unchanged through the `$ExtraArgs` array.

### Essential Components Build (`build-essentials.cmd`)

For rapid iteration, `tools/build/build-essentials.cmd` invokes `build-essentials.ps1` to perform a minimal restore-and-build cycle. This script restores NuGet packages for the solution and compiles only the **runner** and **settings** projects—the minimum set required to run PowerToys—skipping the optional utility modules.

### Full Installer Pipeline (`build-installer.cmd`)

When you need distributable artifacts, `tools/build/build-installer.cmd` orchestrates the complete packaging pipeline via `build-installer.ps1`. This wrapper performs NuGet restoration, compilation, code signing, and generates both MSI and MSIX installers in the `installer/` directory. It accepts installer-specific switches such as `-PerUser` and `-InstallerSuffix`.

## PowerShell Build Implementation

The cmd wrappers delegate all heavy lifting to PowerShell modules designed to be platform-agnostic and directory-agnostic.

### Shared Helper Functions (`build-common.ps1`)

The `tools/build/build-common.ps1` module defines reusable functions consumed by the other scripts:

- **`Ensure-VsDevEnvironment`** – Locates the Visual Studio installation using `vswhere.exe` and initializes the developer shell.
- **`Get-DefaultPlatform`** – Inspects the host CPU architecture to default to `x64` or `arm64`.
- **`BuildProjectsInDirectory`** – Locates the nearest solution or project file and invokes MSBuild with the resolved `/p:Platform=` and `/p:Configuration=` values.

### Core Driver (`build.ps1`)

`tools/build/build.ps1` parses explicit parameters including `-Platform`, `-Configuration`, `-Path`, `-RestoreOnly`, and `-ExtraArgs`. It automatically discovers the build target if invoked from a subdirectory (e.g., `src/modules/fancyzones`), then calls `BuildProjectsInDirectory` with the aggregated MSBuild property flags.

## Step-by-Step Build Instructions

### Prerequisites

Install **Visual Studio 2022** (or later) with the following workloads:
- Desktop development with C++
- .NET desktop development

Ensure `vswhere.exe` is available on your PATH (installed by default with Visual Studio), as `build-common.ps1` depends on it to locate the MSBuild toolchain.

### Fast Essential Build

Run the essentials wrapper to restore packages and compile only the runner and settings UI. This is the fastest way to verify that the core application runs:

```cmd
tools\build\build-essentials.cmd

```

By default, this produces a **Debug** build on the auto-detected platform.

### Full Solution Build

From the repository root (or any project subdirectory), invoke the generic wrapper. Explicitly set the platform and configuration for release builds:

```cmd
tools\build\build.cmd -Platform x64 -Configuration Release

```

If you omit the switches, the script defaults to a Debug build on the detected platform.

### Building Individual Modules

Because `build.ps1` searches upward for the nearest project file, you can rebuild a single module without loading the entire solution in the IDE:

```cmd
cd src\modules\fancyzones
..\..\..\tools\build\build.cmd -Configuration Release

```

### Passing Custom MSBuild Arguments

Append any valid MSBuild properties after the script name. The wrappers forward these to the `$ExtraArgs` array and concatenate them into the final MSBuild command line:

```cmd
tools\build\build.cmd '/p:CIBuild=true' '/p:EnableTelemetry=false'

```

To perform only the NuGet restore step without compiling:

```cmd
tools\build\build.cmd -RestoreOnly

```

### Locating Build Logs

On failure, the scripts generate three diagnostic files alongside the solution with the pattern `build.[Configuration].[Platform].*.log`:

- **`build.Release.x64.errors.log`** – Contains only compilation errors.
- **`build.Release.x64.all.log`** – Full console output from the build.
- **`build.Release.x64.trace.binlog`** – Binary log for analysis in the MSBuild Structured Log Viewer.

These locations are documented in [`tools/build/BUILD-GUIDELINES.md`](https://github.com/microsoft/PowerToys/blob/main/tools/build/BUILD-GUIDELINES.md).

## Summary

- The **cmd wrappers** in `tools/build/` provide a consistent command-line interface across `cmd.exe`, PowerShell, and Visual Studio Developer PowerShell.
- **`build-essentials.cmd`** restores NuGet packages and compiles only the runner and settings UI for rapid development cycles.
- **`build.cmd`** automatically detects platform architecture and accepts standard MSBuild parameters such as `-Platform`, `-Configuration`, and custom `/p:` properties via the `$ExtraArgs` array.
- **`build-installer.cmd`** orchestrates the full pipeline including signing and MSI/MSIX generation.
- The underlying **PowerShell modules** (`build-common.ps1`, `build.ps1`) handle Visual Studio environment initialization via `Enter-VsDevShell` and locate projects from any subdirectory.
- Build outputs include structured logs (error-only, full text, and binary) to diagnose failures quickly.

## Frequently Asked Questions

### What are the prerequisites for building PowerToys with Visual Studio?

Install Visual Studio 2022 or later with the "Desktop development with C++" and ".NET desktop development" workloads. The build scripts also require `vswhere.exe` to be on your PATH so they can locate the Visual Studio installation and initialize the developer environment automatically.

### What is the difference between build.cmd and build-essentials.cmd?

`build.cmd` is a generic wrapper that builds any solution or project in the current directory, defaulting to a Debug configuration on the auto-detected platform. `build-essentials.cmd` specifically targets `PowerToys.slnx` to restore NuGet packages and compile only the runner and settings UI, skipping the optional utility modules for significantly faster build times during development.

### How do I pass custom MSBuild properties to the PowerToys build scripts?

Append any standard MSBuild arguments after the script name. The cmd wrappers forward all trailing arguments to PowerShell, which collects them into the `$ExtraArgs` array and passes them directly to MSBuild. For example: `tools\build\build.cmd '/p:CIBuild=true'` disables code-signing steps suitable for CI pipelines.

### Where can I find build logs if the compilation fails?

The scripts generate three log files in the solution directory: `build.[Configuration].[Platform].errors.log` containing only errors, `.all.log` with full console output, and `.trace.binlog` for detailed analysis in the MSBuild Structured Log Viewer. These files help diagnose missing dependencies or configuration mismatches.