Turns a fresh Windows 11 machine into a clean, distraction-free developer workstation in one command.

This flow installs the tools you'd install anyway, applies the Windows settings you'd change anyway, and sets up WSL + Ubuntu including the reboot in the middle. It is a set of PowerShell scripts: no configuration file to point at, no repo to clone, nothing to install first.

It is idempotent — every change is checked before it's made, so re-running it only fixes what has drifted. It is also resumable — if it fails, or you close the window, running it again picks up where it left off.

Original design and curation: Hamza Usmani.

• Quick start
• Setup actions
• What to expect
• Requirements
• Before you run this
• What it changes
• How it works
• Running it other ways
• Security
• Troubleshooting
• Uninstall and manual cleanup
• Customizing it
• Known limitations
• For contributors

Run this in Windows PowerShell 5.1 or PowerShell 7. Bootstrap requests elevation when needed:

$url = 'https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/src/windows-dev-config/bootstrap.ps1'
& ([scriptblock]::Create((irm $url)))

You'll get one UAC prompt before setup and another after the restart.

Bootstrap avoids publisher-trust prompts by default. Organization policy can require them (AllSigned) or block setup (Restricted).

Both bootstrap.ps1 and dev-config.ps1 accept -Action:

Partial skips changes to Sudo, Developer Mode, Remote Desktop, Edge policies, Explorer's recommended/cloud files, global notifications, the Bluetooth tray icon, web search, search highlights, Widgets, and WinUI templates. It still installs the WinUI Copilot plugin.

$url = 'https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/src/windows-dev-config/bootstrap.ps1'
& ([scriptblock]::Create((irm $url))) -Action Partial

The action is preserved across elevation, PowerShell relaunch, and reboot. Skipped settings are not reverted.

For a fixed-action one-liner, choose one of the signed release wrappers:

irm https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/windows-dev-config/setup-full.ps1 | iex

Replace setup-full.ps1 with the chosen wrapper. Short URLs should point to these repository-root release files, not src/. All three require | iex to execute. The wrappers accept no setup options and verify the Microsoft signature of the downloaded bootstrap.ps1 before running it with the fixed action.

Roughly 30 minutes on a clean machine with a good connection, most of it spent downloading Visual Studio Code, the .NET SDK, PowerToys, and Ubuntu.

Afterwards, open Ubuntu from the Start menu once to create your Linux username and password. Some Explorer and taskbar changes appear after you sign out and back in.

• Windows 11. Built and tested against current Windows 11 releases. A few of the settings only exist on newer builds; on older ones those steps are skipped rather than failing the run. Windows 10 is not supported.
• Administrator rights on the machine, and the ability to accept both UAC prompts.
• Internet access to github.com, api.github.com, raw.githubusercontent.com, the PowerShell Gallery, and the winget package sources. Behind a proxy, the run needs your proxy configured for WinHTTP and for winget.
• Hardware virtualization available to the OS — WSL cannot install without it. On a physical machine that means VT-x / AMD-V enabled in BIOS/UEFI. In a VM it means the host has exposed nested virtualization to the guest. Everything except WSL still works without it; see Troubleshooting.
• About 15 GB of free disk space for the full package set.

You do not need Git, a repository clone, winget configure, the Visual C++ Redistributable, or PowerShell 7 beforehand. The flow handles all of those.

See Setup actions for what each action changes.

Every one of these is listed in full detail in What it changes.

Full applies the setup below, skipping steps already in the desired state.

Installed with winget from the winget source, silently, with agreements accepted:

Before installing packages, setup checks the WinGet module's connection. An RPC connection failure triggers one repair and retry, then a fallback to winget.exe if it can query packages. If neither works, setup stops with a repair message.

A package counts as done only when winget reports it installed and current, so a re-run also picks up available updates.

The Visual C++ runtime is installed before uv, matching Windows' native architecture.

• Cascadia Code NF and Cascadia Mono NF are downloaded from the pinned microsoft/cascadia-code release 2407.24, verified against a known SHA-256, and installed for all users under %SystemRoot%\Fonts. An earlier per-user copy left by a previous run is removed.
• Windows Terminal gets PowerShell 7 as its default profile. After font installation verifies, a one-time, per-user RunOnce update selects Cascadia Mono NF at the next sign-in, without elevation or another setup run. Until then, the current font stays selected so an open Terminal does not warn about a newly installed font. This also works when WSL needs no reboot. If font installation fails, setup flags it and keeps the current font, or uses Cascadia Mono if the missing NF font was already selected.
• Terminal backups: settings.json.bak preserves the original settings across setup, reboot/resume, and the next-sign-in font update. A font choice changed manually after setup is left alone.
• Oh My Posh runs only in Windows Terminal or non-elevated PowerShell 7 sessions, in both modes. Setup updates its block in $PROFILE. If other initialization is present, it leaves the profile unchanged and flags it for manual adjustment.
• A GitHub Copilot profile is added to Windows Terminal as a settings fragment in %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\DevConfig, so it appears in the dropdown without editing your settings file.

These are best-effort: they need the network and a PATH that has just been updated, so a failure is flagged in the summary rather than stopping the run.

• The WinUI templates for dotnet new (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates).
• The microsoft/win-dev-skills marketplace and its WinUI plugin, registered with the GitHub Copilot CLI.

• The WSL platform components, via wsl --install --no-distribution. If that isn't available, the VirtualMachinePlatform and Microsoft-Windows-Subsystem-Linux Windows features are enabled directly with dism.exe instead.
• A restart, if one is needed — see Reboot and resume.
• Ubuntu, via wsl --install -d Ubuntu --no-launch, falling back to --web-download if the Microsoft Store route doesn't complete. The distro's first-run welcome screen is suppressed; open Ubuntu from the Start menu to create your Linux user.

Nothing inside the distro is configured by this flow. For that, see WSL Comfort.

Full runs all phases below. Partial skips Edge and uses fewer settings.

Every step is a triple: a check, an apply, and the same check again.

• If the check passes first time, the step prints already OK and nothing runs.
• If the apply runs but the check still fails afterwards, that's an error — not a silent success.
• Steps that aren't worth stopping the whole run for are marked best-effort. If one of those fails it's reported as flagged, the run continues, and the summary names it at the end so it doesn't scroll past you.

Each step is counted once in the summary, including across a reboot.

Before configuring the machine, setup:

1. Elevates before downloading the payload. Declining UAC stops the run.
2. Uses PowerShell 7, installing it if needed for more reliable WinGet support. If installation fails, setup reports it and continues on Windows PowerShell 5.1.

A machine-wide lock (Global\WindowsDevConfigSetup) means a second copy won't start while one is running — it tells you to switch windows instead of letting two runs fight over the same installs.

Enabling the WSL platform requires a restart. When one is needed, the setup:

1. Saves progress and Terminal backup tracking to devconfig-tally.json, preserving the original settings backup across resume. If saving fails, it does not schedule a resume or restart.
2. Registers a scheduled task named WindowsDevConfigResume that runs at your next logon, as you, at normal privilege after a 30-second delay.
3. Prints a warning and restarts after 10 seconds.

After you sign in, the task opens a window and Windows asks for fresh UAC consent before resuming elevated. Accept it to finish the run, print the combined summary for both halves, and remove the task. If Windows refuses the restart, the setup tells you and leaves the task registered — restart whenever you like and it still resumes.

If Terminal backup tracking cannot be recovered on resume, changes to settings.json are flagged and skipped.

Only one restart is ever performed. If WSL still isn't usable after it, the run stops and explains why rather than rebooting again.

The transcript is devconfig-log.txt next to dev-config.ps1, normally %ProgramData%\CalmOS\devconfig-log.txt. Setup prints the path when it finishes.

The next-sign-in font update writes %LOCALAPPDATA%\CalmOS\terminal-font.log. Keep the setup files in place until that update has run.

The transcript is more verbose than the console on purpose: it records handled errors and raw command output that are deliberately kept off screen. Text in the log that isn't on your console is usually something the run recovered from.

Unsigned development. On a test machine, record the setup user's current policy, then run these commands in both Windows PowerShell 5.1 and PowerShell 7:

Get-ExecutionPolicy -List
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass

CurrentUser affects all scripts for that user and survives reboot; Process does not. Restore the previous policy after testing. Group Policy takes precedence.

From a clone, using unsigned source:

powershell.exe -NoProfile -File .\src\windows-dev-config\dev-config.ps1 -AllowUnsigned

Add -Action Partial for the reduced setup.

Pin a tag, or try a branch. -Ref accepts a branch, tag, or commit SHA. Bootstrap resolves it once so its downloads use the same commit. Pass arguments with a script block, not | iex:

$url = 'https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/src/windows-dev-config/bootstrap.ps1'
& ([scriptblock]::Create((irm $url))) -Ref 'v1.2.3'

Test an unsigned branch. -AllowUnsigned selects src/windows-dev-config/ instead of the signed repository-root copy:

$url = 'https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/src/windows-dev-config/bootstrap.ps1'
& ([scriptblock]::Create((irm $url))) -Ref 'my-branch' -AllowUnsigned

Install without running the configuration. Protecting the files still requires Administrator rights:

$url = 'https://raw.githubusercontent.com/microsoft/WindowsDeveloperConfig/main/src/windows-dev-config/bootstrap.ps1'
& ([scriptblock]::Create((irm $url))) -NoLaunch

Install somewhere else: -InstallRoot 'D:\tools\devconfig'. Use an existing administrator-controlled parent and a location that survives reboot. User-owned paths, user-writable installations, and junctions are rejected.

Already elevated and want it to stay that way: dev-config.ps1 -NoElevate fails fast instead of prompting.

What runs elevated. The setup runs elevated after each UAC prompt. It needs Administrator for the HKLM settings, the WSL Windows features, and machine-wide package installs. The logon task itself runs at normal privilege, so it cannot silently elevate modified files.

What it downloads, and from where. GitHub (this repository, the pinned Cascadia Code release, which is checked against a SHA-256, and the latest microsoft/winget-cli release), the PowerShell Gallery (the Microsoft.WinGet.Client module), the winget package sources, and the GitHub favicon used as the Copilot profile icon. Failing to fetch the icon is not treated as an error, and neither is failing to look up the latest winget version.

Code signing. Production requires valid Microsoft Corporation Authenticode signatures. Before execution, the elevation launcher verifies the bootstrap's signature and confirms the installed copy has the same hash. Bootstrap verifies its security helper before loading it and every payload .ps1 before and after copying, including with -NoLaunch. Each production launch rechecks permissions and signatures before loading other helpers. Failed checks stop setup. -AllowUnsigned skips signature verification for source development.

Web wrappers. Each action wrapper verifies and executes the same downloaded bootstrap text, with no unsigned fallback. irm | iex does not verify the wrapper's own signature; it trusts the HTTPS endpoint. To verify the entry script too, download the wrapper to a file and check its Authenticode signature and Microsoft Corporation signer before running it.

Protected files. Administrators/SYSTEM own the setup and download directories and have write access. Ordinary users have read/execute access only. Unsafe permissions and reparse points are rejected, not repaired.

Execution policy. Production requests process-scoped RemoteSigned for all launches, including PowerShell 7 relaunches and reboot resume. Verified files are unblocked to avoid publisher-trust prompts. Organization policy takes precedence: AllSigned may still prompt; Restricted blocks setup. Setup does not change saved policies or add trusted publishers. -AllowUnsigned leaves execution policy unchanged.

What it does not do. It doesn't collect or send telemetry, doesn't sign you in to anything, doesn't change credentials or Windows Defender settings, and doesn't touch files in your user profile beyond the PowerShell profile and Windows Terminal settings described above.

Get-ScheduledTask -TaskName WindowsDevConfigResume

netsh winhttp show proxy

Run in an elevated PowerShell window:

& "$env:ProgramData\CalmOS\dev-config.ps1" -Action Uninstall

From source: .\src\windows-dev-config\dev-config.ps1 -AllowUnsigned -Action Uninstall. bootstrap.ps1 also accepts -Action Uninstall. Cleanup uses Windows PowerShell to remove PowerShell 7. Per-user tools are removed through temporary tasks in the same account's non-elevated, signed-in session. Git and Visual Studio Code use their registered Inno uninstallers without progress windows or automatic restarts; other installation types use WinGet. Some uninstallers may still request Administrator approval.

Cleanup runs without confirmation and permanently deletes the Ubuntu distro and its files. It uninstalls WSL and the tools below, including pre-existing, machine-wide, and all-user MSIX installations. Cleanup covers Full's configuration regardless of which setup action ran. It does not restore previous settings.

• Settings: disable Sudo, Developer Mode, and Remote Desktop; reset Explorer, Start, search, notification, Bluetooth tray, taskbar End Task, Widgets, Edge policies, long-path, and WSL first-run settings; select the unrestricted QuietHours profile and switch app/system themes to light.
• Terminal: cancel any pending next-sign-in font update; remove defaultProfile, profiles.defaults, PowerShell/Copilot/Ubuntu profile entries (including dynamically generated PowerShell entries), and the Copilot fragment.
• Integrations: remove the managed Oh My Posh profile block, WinUI template package, and win-dev-skills marketplace. Custom profile code and unrelated plugins are preserved; a marketplace still used by other plugins is flagged rather than force-removed.
• Tools: remove uv executables, caches, and local data; NVM; the WinUI Copilot plugin; Node.js; Copilot; Python 3.14 and its launcher/install manager; Git; GitHub CLI; Oh My Posh; Azure CLI; Coreutils; .NET SDK 10; Intelligent Terminal; PowerToys; Visual Studio Code; Windows App CLI; and PowerShell 7.

Failed or timed-out steps are flagged; cleanup continues. Long-running commands show progress. Unlisted settings, fonts, Windows Terminal, the Visual C++ runtime, shared prerequisites (WinGet and Windows optional features), and setup files/logs remain.

Additional manual cleanup:

• Packages: winget uninstall --id <id> using the ids in Packages.
• Explorer, Start and search settings: all of them are also in Settings and Explorer's Options dialog. Sign out and back in for them to take effect.
• Windows Terminal: restore the settings.json.bak written next to settings.json.
• The Copilot Terminal profile: delete %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\DevConfig.
• Ubuntu: wsl --unregister Ubuntu. This permanently deletes the distro's file system.
• The setup itself: delete %ProgramData%\CalmOS from an elevated terminal.

Edit the files under src\windows-dev-config in your clone, then run the unsigned-source command.

A phase is just a file plus an entry in the $phases list. Files prefixed with _ are shared helpers, not phases.

Setup and cleanup use the same phase files and definitions. Phases marked Uninstall = $true provide cleanup steps. Package entries use KeepOnUninstall, AdditionalUninstallIds, UninstallOrder, and InnoUninstall for cleanup differences; registry entries are reset by default. New-DevConfigRegistryStep -Reset applies ResetValue when specified; otherwise it deletes only the named value.

Source of truth for this flow is src/windows-dev-config/. The copy at the repository root is the Authenticode-signed release copy, regenerated by the sign pipeline — don't edit it directly. See src/docs/development.md.

Adding a phase means adding one file and one line in the $phases list. Adding a step to an existing phase means one New-DevConfigStep call. Keep every step's check cheap and side-effect free — it runs on every invocation, including the fast path where nothing needs doing.