Win11Debloat Administrator & Developer Guide

This guide is for system administrators, IT deployers, and developers who need to understand how Win11Debloat works internally: its architecture, the configuration files that drive it, the registry-application engine, how to deploy it at scale, its security model, and where to extend it. For day-to-day usage and the full option reference, see the User Guide.

1. Executive Summary

Win11Debloat is a config-driven PowerShell + WPF application for debloating and customizing Windows 11/10. Its defining architectural trait is that the behavior lives in data, not code: a small, generic PowerShell engine reads JSON configuration files and .reg registry files to decide what to do. Adding a new tweak usually means adding a .reg file and a JSON entry — not writing PowerShell.

2. Architecture

2.1 High-level component map

                         Run.bat ──► elevates ──► Win11Debloat.ps1
  irm debloat.raphi.re ──────────────────────────────┘
                                                      │
                       ┌──────────────────────────────┴───────────────────────────┐
                       │              Win11Debloat.ps1 (orchestrator)               │
                       │  • param block = the full CLI/feature surface              │
                       │  • admin + language-mode guards                            │
                       │  • dot-sources every Scripts/**/*.ps1                      │
                       │  • loads Config/Features.json into $script:Features        │
                       │  • routes: GUI ▸ CLI ▸ Config/Defaults/SavedSettings       │
                       └───────┬───────────────────────┬───────────────────────────┘
                               │                       │
              ┌────────────────▼─────┐       ┌─────────▼──────────────┐
              │  Scripts/GUI (WPF)   │       │  Scripts/CLI (text)    │
              │  Schemas/*.xaml      │       │  menu / pending changes │
              └────────────────┬─────┘       └─────────┬──────────────┘
                               └───────────┬───────────┘
                                           ▼
                        ┌──────────────────────────────────────────┐
                        │   ExecuteAllChanges (Scripts/Features)     │
                        │   1. registry backup (JSON snapshot)       │
                        │   2. optional restore point                │
                        │   3. ExecuteParameter per selected key     │
                        └───────────────┬───────────────────────────┘
                                        ▼
        ┌───────────────────────────────┼─────────────────────────────────┐
        ▼                               ▼                                   ▼
  ImportRegistryFile             RemoveApps                         EnableWindowsFeature
  (Regfiles/*.reg → reg import,  (Appx + provisioned;               (DISM via
   PS fallback writer)           winget for OneDrive/Edge)           Enable-WindowsOptionalFeature)

2.2 The data-driven principle

Win11Debloat separates what from how:

• What to do is described declaratively in Config/*.json and the Regfiles/ tree.
• How to do it is a generic interpreter in Scripts/. The central dispatcher, ExecuteParameter, looks up each selected option in $script:Features (loaded from Features.json). If the feature carries a RegistryKey, it simply imports that .reg file. Only options with non-registry behavior (app removal, enabling Windows features, clearing the Start menu) have bespoke code branches.

This is why the user-facing surface — the ~100 parameters, the tweak catalog, the app list — is best understood by reading the JSON and .reg files, not the PowerShell.

2.3 Directory layout

2.4 Run routing

Win11Debloat.ps1 decides how to run based on the parameters it receives:

1. No parameters → launch the GUI (Show-MainWindow). If WPF can't load, fall back to the CLI menu.
2. -CLI, -User, -Sysprep, or -AppRemovalTarget → use the CLI menu (launchInCLI is set true for deployment-oriented runs).
3. -RunDefaults / -RunDefaultsLite → load DefaultSettings.json and the chosen app option.
4. -RunSavedSettings → load LastUsedSettings.json.
5. -Config <file> → import a config JSON into parameters.
6. Only tweak/app switches given → apply them directly.

A parameter is classified as a control parameter ($script:ControlParams: WhatIf, Confirm, Verbose, Debug, LogPath, Silent, Sysprep, User, NoRestartExplorer, RunDefaults, RunDefaultsLite, RunSavedSettings, Config, RunAppsListGenerator, CLI, AppRemovalTarget) or an actionable parameter (a tweak/app). If only control parameters are present, the script exits without changes (The script completed without making any changes.).

2.5 Concurrency model

Win11Debloat is single-process, but it must keep the WPF UI responsive during long operations (app removal, DISM, restore points). Scripts/Threading/Invoke-NonBlocking.ps1 runs work in a background PowerShell runspace while the UI thread pumps messages via DoEvents (~60 fps). In CLI mode the same function runs the scriptblock inline. Several operations also accept a -TimeoutSeconds so a hung call (e.g. winget list, Checkpoint-Computer) can't freeze the tool.

3. System Requirements

Note

Win11Debloat ensures System32 is on PATH for its session (it warns and prepends it if missing), because it shells out to reg, powercfg, quser, and winget.

4. Configuration Mastery

All four JSON files share a top-level Version field that the loader validates; a mismatch is rejected.

4.1 Config/Apps.json — the removable-app catalog

Defines every app the tool knows how to remove, plus presets.

{
  "Version": "1.1",
  "Apps": [
    {
      "FriendlyName": "Clipchamp",
      "AppId": "Clipchamp.Clipchamp",
      "Description": "Video editor from Microsoft",
      "SelectedByDefault": true,
      "Recommendation": "safe"
    }
  ],
  "Presets": [
    { "Name": "Xbox Gaming apps", "AppIds": ["Microsoft.GamingApp", "Microsoft.XboxGameOverlay", "Microsoft.XboxGamingOverlay"] }
  ]
}

Important

Apps marked unsafe (Microsoft Store, Windows Terminal, Xbox Identity Provider, Xbox TCUI/Speech-to-Text, Get Help, Edge) trigger an explicit confirmation dialog (ConfirmUnsafeAppRemoval) because removing them can break sign-in, app installation, or the running console.

4.2 Config/Features.json — the tweak catalog

This is the heart of the data-driven design. Each entry maps a tweak to its .reg files and constraints:

{
  "FeatureId": "DisableTelemetry",
  "Label": "Disable telemetry, tracking & targeted ads",
  "ToolTip": "...",
  "Category": "Privacy & Suggested Content",
  "RegistryKey": "Disable_Telemetry.reg",
  "ApplyText": "Disabling telemetry...",
  "RegistryUndoKey": "Enable_Telemetry.reg",
  "MinVersion": null,
  "MaxVersion": null
}

Features.json also defines Categories (with Segoe MDL2 icon glyphs) and UiGroups — radio-style groups where several FeatureIds are mutually exclusive (taskbar search style, multi-monitor combine modes, Explorer launch location, drive-letter position, Alt+Tab tab count).

Tip

To add a tweak: drop Apply.reg and Undo.reg into Regfiles/ (and Regfiles/Sysprep/ if it should support offline application), then add a Features.json entry pointing at them. No PowerShell change is needed for a pure registry tweak.

4.3 Config/DefaultSettings.json — the "Default mode" preset

A flat list of { Name, Value } settings applied by -RunDefaults/-RunDefaultsLite. The shipped default enables 17 privacy/quality tweaks (telemetry, suggestions, Edge ads, lock-screen tips, Bing, Store suggestions, Copilot, Recall, Click-to-Do, AI autostart, widgets, chat, known file extensions, drag tray, 3D objects, Modern Standby networking) plus CreateRestorePoint.

4.4 Runtime files

4.5 The deployment config format (-Config)

ImportConfigToParams reads a version 1.0 JSON with up to three sections, mapping each to parameters:

This is exactly what the GUI's Export config produces, making it the canonical artifact for repeatable deployments.

5. The Tweak-Application Engine

5.1 ExecuteAllChanges (orchestrator)

Located in Scripts/Features/ExecuteChanges.ps1. The sequence:

1. Build the list of actionable parameter keys (excluding control params, Apps, CreateRestorePoint).
2. If any selected feature is registry-backed, create a registry backup first (New-RegistrySettingsBackup). A backup failure aborts the run before any change.
3. If -CreateRestorePoint was set, create a System Restore point.
4. For each actionable key, call ExecuteParameter, reporting progress through $script:ApplyProgressCallback (wired to the GUI progress bar).
5. Tally any registry import failures and report them.

5.2 ExecuteParameter (dispatcher)

For a feature with both RegistryKey and ApplyText, it calls ImportRegistryFile. A few features have extra logic layered on top:

5.3 ImportRegistryFile — apply with fallback

Scripts/Features/ImportRegistryFile.ps1 is the workhorse:

1. Choose the source directory: Regfiles/ normally, or Regfiles/Sysprep/ when -User/-Sysprep is active (offline hive).
2. For offline application, reg load HKU\Default <NTUSER.DAT> mounts the target user's hive.
3. Run reg import <file> inside Invoke-NonBlocking.
4. If reg import fails (non-zero exit or error), fall back to a hand-rolled PowerShell writer (Invoke-RegistryOperationsFromRegFile) that parses the .reg and applies each operation via the .NET registry API.
5. Always reg unload HKU\Default in a finally block.

This dual path is why most "failed to write to the registry" errors self-recover.

5.4 The .reg parser (Get-RegFileOperations)

Scripts/Helpers/Get-RegFileOperations.ps1 parses a .reg file into structured operations, supporting:

• Continuation lines (trailing \), comments (;), and the editor header.
• [-Key] → DeleteKey; "name"=- → DeleteValue; @= → default value.
• Value types: dword:, qword:, hex:/hex(2)/hex(7) (Binary / expandable string / multi-string), and quoted strings.

Invoke-RegistryOperation then applies each via Get-RegistryRootKey + Split-RegistryPath (supports HKCU/HKLM/HKCR/HKU/HKCC, normalizes HKU\.DEFAULT). Access-denied operations are logged and skipped, and a "could apply nothing" condition throws.

5.5 Backup & restore

• Backup (BackupRegistryState.ps1 + BackupRegistrySnapshotCapture.ps1): for the selected registry-backed features, it derives a capture plan of exactly which keys/values each .reg touches, snapshots their current state (value, kind, sub-keys), and writes a JSON payload (Version, Target, SelectedFeatures, RegistryKeys) to Backups/. Target can be CurrentUser:<name>, User:<name>, or DefaultUserProfile.
• Restore (RestoreRegistryBackup.ps1 + RestoreRegistryApplyState.ps1): validates the backup (version, target, and that every snapshot path is allow-listed by the recorded SelectedFeatures — preventing tampered backups from writing arbitrary keys), then re-applies each snapshot, loading the offline hive when the target is a user/default profile.

Note

The restore allow-list check is a deliberate integrity control: a backup may only touch registry paths that its declared features are known to modify. Snapshots referencing unexpected paths fail validation.

5.6 App removal (RemoveApps)

Scripts/AppRemoval/RemoveApps.ps1 resolves a target scope (AllUsers default, CurrentUser, or a specific user SID) and then, per app:

• OneDrive / Edge → WinGet uninstall. In -User/-Sysprep (offline) mode it instead imports an Uninstall_*.reg that schedules the uninstall for the target user. If WinGet can't remove Edge, it offers ForceRemoveEdge.
• All other apps → Get-AppxPackage … | Remove-AppxPackage (and Remove-ProvisionedAppxPackage for AllUsers, so the app doesn't return for new users).

ForceRemoveEdge (Scripts/AppRemoval/ForceRemoveEdge.ps1) sets AllowUninstall, creates a stub, runs Edge's own uninstaller with --force-uninstall, removes shortcuts, and cleans Run keys.

5.7 Finishing up

RestartExplorer warns about any selected RequiresReboot features, then restarts explorer.exe — unless -User/-Sysprep/-NoRestartExplorer is set, or the PowerShell process architecture doesn't match the OS (in which case it asks you to reboot).

6. Deployment

6.1 Single machine, unattended

.\Win11Debloat.ps1 -RunDefaults -Silent -CreateRestorePoint

6.2 Fleet deployment with a shared config

1. Build a config in the GUI → Export config → debloat.json.
2. Distribute the script folder + debloat.json (GPO, Intune, SCCM, MDT, or a setup script).
3. Run per machine:

.\Win11Debloat.ps1 -Config "C:\Deploy\debloat.json" -Silent

6.3 Image / golden-master deployment (Sysprep)

Apply to the Default profile so every new user inherits the changes:

.\Win11Debloat.ps1 -RunSavedSettings -Sysprep -Silent

• Uses Regfiles/Sysprep/ against the offline Default\NTUSER.DAT hive.
• OneDrive/Edge removal is deferred via a per-user scheduled task.
• Explorer is not restarted; finalize during image capture / first boot.
• Not supported on Windows 10.

6.4 Targeting another (signed-out) user

.\Win11Debloat.ps1 -RunSavedSettings -User "Alice" -Silent

The target must exist and be signed out (validated via quser); you cannot target your own account this way.

Tip

Combine -LogPath "<share>\logs" to centralize transcripts across a fleet, and -NoRestartExplorer when you'll reboot as part of the deployment anyway.

7. Operations

Note

System Restore points are throttled by Windows to one per 24 hours; Win11Debloat detects a recent point and skips creating a duplicate rather than failing.

8. Security Analysis

Caution

Treat -Silent carefully: it suppresses all confirmations, including the unsafe-app warnings. When scripting Silent runs, vet the app list so you don't unintentionally remove sign-in-critical packages.

9. Code Quality & Patterns

• Declarative core. New behavior is data (.reg + JSON), not code — low-risk to extend, easy to audit.
• Single dispatcher. ExecuteParameter centralizes how every option is applied; special cases are explicit switch arms.
• Defensive I/O. JSON loads validate Version; settings/app-list parsing tolerate comments, arrays-vs-strings, and missing files; user/SID resolution (ResolveUserProfileContext) tries NTAccount → local lookup → ProfileList registry, with a cache.
• UI responsiveness as a first-class concern. Invoke-NonBlocking + DoEvents keep WPF alive during slow operations; timeouts guard winget/restore-point calls.
• Idempotent, reversible changes. Every tweak pairs an apply and undo .reg; a pre-change snapshot is always taken.
• Build-aware. MinVersion/MaxVersion gates and a Modern-Standby capability check prevent applying inapplicable tweaks.

Conventions: Verb-Noun for new helper functions (e.g. Get-RegFileOperations, Restore-RegistryKeySnapshot); older top-level functions use bare names (RemoveApps, ExecuteAllChanges). Script-scoped state ($script:Params, $script:Features, $script:GuiWindow, $script:CancelRequested) is the shared bus between modules.

10. Module Reference

11. Known Issues & Improvement Opportunities

Drawn from the public issue tracker and source review.

Note

Feature requests in the tracker (disable service startup, OneDrive/Edge autostart, clear taskbar pins, Win10 Explorer ribbon, "My Computer" on desktop) indicate the natural growth areas — most could ship as new Features.json + .reg pairs without engine changes.

12. Quick Reference

# Default debloat, unattended, with restore point
.\Win11Debloat.ps1 -RunDefaults -Silent -CreateRestorePoint

# Tweaks only (no app removal)
.\Win11Debloat.ps1 -RunDefaultsLite -Silent

# Re-apply last used settings
.\Win11Debloat.ps1 -RunSavedSettings -Silent

# Apply an exported config
.\Win11Debloat.ps1 -Config "C:\Deploy\debloat.json" -Silent

# Specific tweaks + targeted app removal
.\Win11Debloat.ps1 -DisableTelemetry -DisableBing -EnableDarkMode `
                   -RemoveApps -Apps "Microsoft.BingNews,Microsoft.ZuneVideo" -Silent

# New-user defaults (imaging)
.\Win11Debloat.ps1 -RunSavedSettings -Sysprep -Silent

# Another signed-out user
.\Win11Debloat.ps1 -RunSavedSettings -User "Alice" -Silent