Configure PowerToys with PowerShell DSC

PowerToys includes a PowerShell Desired State Configuration (DSC) module that integrates with WinGet configuration files, enabling automated deployment and configuration of PowerToys utilities across Windows systems.

Overview

The Microsoft.PowerToys.Configure DSC resource allows you to:

• Install and configure PowerToys in a single WinGet configuration file.
• Declare desired settings for PowerToys utilities.
• Version control your PowerToys configuration.
• Deploy consistent PowerToys settings across multiple machines.
• Integrate with existing PowerShell DSC workflows.

Available since: PowerToys v0.80.0

Prerequisites

Before using PowerShell DSC with PowerToys, ensure you have:

• PowerShell 7.2 or higher - Required for DSC v2 support
• PSDesiredStateConfiguration 2.0.7 or later - The PowerShell DSC module. Refer to the PowerShell DSC documentation for installation instructions
• WinGet v1.6.2631 or later - For configuration file support. Download from the WinGet releases page
• PowerToys - Installed via the PowerToys installer

Installation

The Microsoft.PowerToys.Configure module is automatically installed with PowerToys. The module location depends on the installation scope:

• Per-user installation: %USERPROFILE%\Documents\PowerShell\Modules\Microsoft.PowerToys.Configure
• Machine-wide installation: %ProgramFiles%\WindowsPowerShell\Modules\Microsoft.PowerToys.Configure

Usage

Direct invocation with PowerShell

You can invoke the DSC resource directly using PowerShell:

Invoke-DscResource -Name PowerToysConfigure -Method Set `
  -ModuleName Microsoft.PowerToys.Configure `
  -Property @{
    Awake = @{
      Enabled = $false
      Mode = "TIMED"
      IntervalMinutes = "10"
    }
  }

WinGet configuration files

The recommended approach is to use WinGet configuration files (YAML format) to define your PowerToys settings. This allows you to install PowerToys and apply configuration in a single, declarative file.

Example configuration:

# configuration.dsc.yaml
properties:
  resources:
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: installPowerToys
      directives:
        description: Install PowerToys
        allowPrerelease: true
      settings:
        id: Microsoft.PowerToys
        source: winget

    - resource: Microsoft.PowerToys.Configure/PowerToysConfigure
      dependsOn:
        - installPowerToys
      directives:
        description: Configure PowerToys
      settings:
        ShortcutGuide:
          Enabled: false
          OverlayOpacity: 50
        FancyZones:
          Enabled: true
          FancyzonesEditorHotkey: "Shift+Ctrl+Alt+F"
        FileLocksmith:
          Enabled: false
  configurationVersion: 0.2.0

Apply the configuration:

winget configure .\configuration.dsc.yaml

This command installs the latest version of PowerToys (or ensures it's already installed) and applies the specified settings.

Configuration examples

More examples can be found in the PowerToys repository.

Example 1: Enable and configure FancyZones

properties:
  resources:
    - resource: Microsoft.PowerToys.Configure/PowerToysConfigure
      directives:
        description: Configure FancyZones
      settings:
        FancyZones:
          Enabled: true
          FancyzonesShiftDrag: true
          FancyzonesMouseSwitch: false
          FancyzonesOverrideSnapHotkeys: true
          FancyzonesEditorHotkey: "Win+Shift+`"
  configurationVersion: 0.2.0

Example 2: Configure multiple utilities

properties:
  resources:
    - resource: Microsoft.PowerToys.Configure/PowerToysConfigure
      directives:
        description: Configure multiple PowerToys utilities
      settings:
        GeneralSettings:
          Startup: true
          Theme: "dark"
          EnableWarningsElevatedApps: true
        ColorPicker:
          Enabled: true
          ActivationShortcut: "Win+Shift+C"
          CopiedColorRepresentation: "HEX"
        PowerRename:
          Enabled: true
          MRUEnabled: true
          MaxMRUSize: 10
        Awake:
          Enabled: true
          Mode: "INDEFINITE"
          KeepDisplayOn: true
  configurationVersion: 0.2.0

Example 3: Install specific PowerToys version and configure

properties:
  resources:
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: installPowerToys
      directives:
        description: Install PowerToys version 0.95.0
      settings:
        id: Microsoft.PowerToys
        source: winget
        version: "0.95.0"

    - resource: Microsoft.PowerToys.Configure/PowerToysConfigure
      dependsOn:
        - installPowerToys
      directives:
        description: Configure PowerToys utilities
      settings:
        AlwaysOnTop:
          Enabled: true
          Hotkey: "Win+Ctrl+T"
          FrameEnabled: true
          FrameThickness: 5
          FrameColor: "#FF0000FF"
  configurationVersion: 0.2.0

Available configuration settings by module

The following sections provide a complete reference of all available configuration settings for each PowerToys utility.

AlwaysOnTop

Awake

ColorPicker

CropAndLock

EnvironmentVariables

FancyZones

FileLocksmith

FindMyMouse

Hosts

ImageResizer

KeyboardManager

MeasureTool

Measure Tool is the internal name for Screen Ruler.

MouseHighlighter

MouseJump

MousePointerCrosshairs

MouseWithoutBorders

PastePlain

Peek

PowerAccent

PowerAccent is the internal name for Quick Accent.

PowerLauncher

PowerLaucher is the internal name for PowerToys Run.

PowerToys Run plugin configuration

PowerToys Run plugins can be configured in the Plugins property. A sample can be found in the PowerToys repository.

These are the available properties to configure each plugin:

PowerOcr

PowerOcr is the internal name for Text Extractor.

PowerPreview

PowerRename

RegistryPreview

ShortcutGuide

VideoConference

GeneralSettings

Migrating to Microsoft DSC

If you're considering moving to the newer Microsoft DSC implementation (available since PowerToys v0.95.0), see Configure with Microsoft DSC. The Microsoft DSC approach offers:

• Standalone PowerToys.DSC.exe tool without PowerShell dependencies
• Individual resource types for each utility (better modularity)
• Full JSON schema generation and validation
• DSC manifest generation capabilities
• Cross-platform readiness

See also

• Configure PowerToys with DSC overview
• Configure with Microsoft DSC
• PowerToys installation guide
• WinGet configuration documentation
• PowerShell DSC documentation
• PowerToys DSC examples