Configuring Windows Registry

Modify Windows registry entries (add, change, and remove). Apply registry settings across HKLM, HKCU, HKDU (Default User), HKCR, and HKU hives.

Overview

The windowsRegistry module manages Windows registry modifications including add and remove operations. It processes registry entries across different registry hives including special handling for Default User profile settings.

The module supports the following registry hives:

• HKLM (HKEY_LOCAL_MACHINE) - machine-wide settings
• HKCU (HKEY_CURRENT_USER) - current user settings
• HKDU (Default User) - settings applied to new user profiles by loading NTuser.dat from the Default User profile
• HKCR (HKEY_CLASSES_ROOT) - file associations and COM registrations
• HKU (HKEY_USERS) - all user profile settings

For each registry item, the module performs the following steps:

1. Validates OS build requirements (minOSbuild and maxOSbuild)
2. Filters the item based on current OS build compatibility
3. Performs the specified action:
   • add - creates or updates the registry value with the specified type and data
   • remove - deletes the specified registry value
4. Logs the operation result

When HKDU items are present in the configuration, the module automatically loads the Default User registry hive (NTuser.dat) as HKLM\.DEFAULTUSER before processing. After all registry items are processed, the hive is safely unloaded with retry logic (up to 3 attempts) and garbage collection to release file handles.

Note

Binary registry values (REG_BINARY) are skipped under Constrained Language Mode and logged as a warning.

Configuration

The following shows the windowsRegistry configuration structure with two example items - one targeting HKLM and one targeting the Default User hive (HKDU) with OS build gating.

{
  "windowsRegistry": {
    "enabled": true,
    "items": [
      {
        "description": "Enable Win32 Long Paths",
        "minOSbuild": "",
        "maxOSbuild": "",
        "item": "add",
        "root": "HKLM",
        "Path": "SYSTEM\\CurrentControlSet\\Control\\FileSystem",
        "Name": "LongPathsEnabled",
        "Type": "REG_DWORD",
        "Value": "1"
      },
      {
        "description": "Hide 'Task View Button' icon from Taskbar",
        "minOSbuild": "22000",
        "maxOSbuild": "",
        "item": "add",
        "root": "HKDU",
        "Path": "Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced",
        "Name": "ShowTaskViewButton",
        "Type": "REG_DWORD",
        "Value": "0"
      }
    ]
  }
}

Dataset properties

The following properties are supported in the windowsRegistry section.

Property	Description	Type	Required
windowsRegistry
enabled	Enable or disable the module	Boolean	No
items (array)
description	Description of the registry change - used for logging and readability	String	Yes
minOSbuild	Minimum Windows build number required for this item. Empty string means no restriction	String	No
maxOSbuild	Maximum Windows build number allowed for this item. Empty string means no restriction	String	No
item	Registry operation type - add, remove, or modify	String	Yes
root	Registry hive - HKLM, HKCU, HKDU, HKCR, or HKU	String	Yes
Path	Registry key path without the root (e.g., Software\Microsoft\Windows\CurrentVersion)	String	Yes
Name	Registry value name. Use * with remove to delete the entire key	String	Yes
Type	Registry value type - REG_SZ, REG_EXPAND_SZ, REG_BINARY, REG_DWORD, REG_MULTI_SZ, or REG_QWORD	String	No
Value	Registry value data	String	No

Reference

The commands below can be used to inspect or verify registry values configured by this module.

Read registry values

Read a specific registry value from HKLM.

Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" | Select-Object "LongPathsEnabled"

List all values under a key

List all registry values under a specific key path.

Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Advanced" | Format-List

Default User registry hive

Manually load and inspect the Default User registry hive.

reg load "HKLM\.DEFAULTUSER" "$env:SystemDrive\Users\Default\NTuser.dat"
Get-ItemProperty -Path "HKLM:\.DEFAULTUSER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced" | Select-Object "ShowTaskViewButton"
reg unload "HKLM\.DEFAULTUSER"

Related resources

For more information, see the following resources.

• about_Registry_Provider - PowerShell reference for working with the registry

---

Page revised: March 4, 2026