Skip to main content

​
Settings architecture

PowerToys uses a distributed settings system where the Settings UI communicates with the PowerToys Runner and individual modules through inter-process communication (IPC).

​
Components

Settings UI

WinUI application for configuring all PowerToys utilities

Runner

Main process that loads modules and handles hotkeys

IPC Communication

Named pipes for real-time settings synchronization

JSON Storage

Settings persisted as JSON files in LocalApplicationData

​
IPC communication

The Settings UI communicates with the Runner using JSON messages over named pipes: 
// Example IPC message format
{
  "powertoys": {
    "<module_name>": {
      // Module-specific settings
    }
  }
}
When you change a setting in the UI:
1

User modifies setting

The Settings UI updates its ViewModel and validates the change
2

Send IPC message

Settings UI sends JSON message to Runner via named pipe at src/settings-ui/Settings.UI/ViewModels/*ViewModel.cs
3

Runner processes message

Runner receives message and forwards to appropriate module at src/runner/
4

Settings persisted

Module saves settings to JSON file in %LOCALAPPDATA%\Microsoft\PowerToys\

​
General settings

General settings control PowerToys behavior across all utilities. These are defined in GeneralSettings.cs:

​
Startup and system behavior

Controls whether PowerToys starts when you log in to Windows. This creates a scheduled task for reliable startup.Registry key: Software\Policies\PowerToys\ConfigureRunAtStartupCan be controlled by GPO: Yes (since v0.89.0)
Determines if PowerToys runs with administrator privileges. Required for some features to work with elevated applications.Setting: GeneralSettings.RunElevatedDefault: false
Controls visibility of the PowerToys icon in the system tray.Setting: GeneralSettings.ShowSysTrayIconDefault: true
When enabled, the tray icon color adapts to Windows theme (light/dark).Setting: GeneralSettings.ShowThemeAdaptiveTrayIconDefault: Varies by theme

​
Theme settings

PowerToys supports three theme modes defined in GeneralSettings.cs:139-150:
  • Dark - Force dark theme
  • Light - Force light theme
  • System - Follow Windows theme (default)
{
  "theme": "system",
  "system_theme": "light"
}

​
Updates and notifications

{
  "show_new_updates_toast_notification": true,
  "download_updates_automatically": false,
  "show_whats_new_after_updates": true
}

​
Experimentation and diagnostics

Experimentation

Allows participation in feature experiments (Windows Insider builds only)Setting: EnableExperimentationGPO: AllowExperimentation

Diagnostic data

Enables telemetry to help improve PowerToysGPO: AllowDataDiagnostics (since v0.86.0)

​
Quick Access

Quick Access provides fast access to PowerToys modules via a keyboard shortcut. 
{
  "enable_quick_access": true,
  "quick_access_shortcut": {
    "win": true,
    "ctrl": false,
    "alt": true,
    "shift": false,
    "code": 80
  }
}
The shortcut is defined using virtual key codes. See Keyboard shortcuts for more details.

​
Module enable/disable

Each PowerToys utility can be individually enabled or disabled. The enabled state is stored in the EnabledModules class:

​
Module state management

{
  "enabled": {
    "AlwaysOnTop": true,
    "Awake": false,
    "ColorPicker": true,
    "FancyZones": true,
    "PowerLauncher": true,
    // ... other modules
  }
}

​
GPO-controlled module states

Administrators can enforce module states via Group Policy. Individual module policies override the global utility policy.
GPO policies have the following precedence:
  1. Individual module policy (e.g., ConfigureEnabledUtilityColorPicker)
  2. Global utility policy (ConfigureAllUtilityGlobalEnabledState)
  3. User preference
Example GPO configuration at src/gpo/assets/PowerToys.admx:62-71: 
<policy name="ConfigureAllUtilityGlobalEnabledState" 
        key="Software\Policies\PowerToys" 
        valueName="ConfigureGlobalUtilityEnabledState">
  <enabledValue>
    <decimal value="1" />
  </enabledValue>
  <disabledValue>
    <decimal value="0" />
  </disabledValue>
</policy>

​
Settings file locations

PowerToys stores settings as JSON files in the Windows LocalApplicationData folder.

​
Primary locations

%LOCALAPPDATA%\Microsoft\PowerToys\

​
File structure

%LOCALAPPDATA%\Microsoft\PowerToys\
├── settings.json              # General settings
├── Logs\                      # Application logs
├── AlwaysOnTop\              
│   └── settings.json         # Always On Top settings
├── ColorPicker\
│   └── settings.json         # Color Picker settings
├── FancyZones\
│   ├── settings.json         # FancyZones settings
│   └── zones-settings.json   # Zone layouts
├── PowerToys Run\
│   └── settings.json         # PowerToys Run settings
└── <module-name>\
    └── settings.json         # Each module has its own folder

​
Settings file format

All settings files follow a consistent structure defined in src/settings-ui/Settings.UI.Library/: 
{
  "name": "<ModuleName>",
  "version": "1.0",
  "properties": {
    // Module-specific properties
  }
}

​
Accessing settings programmatically

Settings are accessed via the SettingsRepository pattern implemented in src/settings-ui/Settings.UI.Library/: 
// From GeneralViewModel.cs:116-120
private ISettingsRepository<GeneralSettings> _settingsRepository;
GeneralSettingsConfig = settingsRepository.SettingsConfig;

// Settings are automatically watched for external changes
_settingsRepository.SettingsChanged += OnSettingsChanged;

​
Settings backup and restore

Starting with recent versions, PowerToys includes settings backup and restore functionality:
1

Configure backup location

Set a backup directory in General settings
2

Backup settings

Exports all module settings to the backup location
3

Restore settings

Imports settings from backup directory
Backup configuration is handled in GeneralViewModel.cs:95-110.

​
Configuration via command line

Some settings support command-line configuration through the ICmdLineRepresentable interface implemented by HotkeySettings and other types. 
# Example: Set a hotkey via command line
powertoys.exe --set-hotkey "Win+Alt+P"
See HotkeySettings.cs:253-288 for parsing implementation.

​
Settings validation

Settings are validated when loaded to ensure integrity:
  • Type checking - JSON deserialization validates types
  • Range validation - Numeric values checked against valid ranges
  • Conflict detection - Hotkeys checked for conflicts with system shortcuts
Manually editing settings files while PowerToys is running may cause conflicts. Changes are detected via file watchers, but race conditions can occur.

Keyboard shortcuts

Complete list of keyboard shortcuts for all utilities

Group Policy

Enterprise configuration via Group Policy

Build docs developers (and LLMs) love

Get started for freeTalk to us