Windows 11 developer setup — the first hour after unboxing

There are two flavors of Windows development: (a) do everything inside WSL2/Linux, (b) run natively with PowerShell + Git Bash. This guide sets up both so you can pick by case. Node/Go/Python? WSL2 wins by a wide margin. .NET, games, Tauri, Win32 APIs? Native is the answer.

Target: Windows 11 (22H2 or newer) with winget available. Windows 10 mostly works, with minor winget differences.

TL;DR

1. Four Windows 11 system settings (Explorer extensions/hidden, clipboard history, virtual desktop shortcuts)
2. winget installs eight essentials in one line (Git, GH CLI, Windows Terminal, PowerShell 7, VS Code, mise, ripgrep, fzf)
3. WSL2 + Ubuntu 24.04: wsl --install -d Ubuntu-24.04
4. Git globals + SSH ed25519 → register on GitHub → gh auth login

Prerequisites

• Windows 11 22H2+ — confirm with winver. This is the first build with winget bundled.
• Admin rights — needed for WSL2 install and some system-scope winget packages.
• Internet + Microsoft account (effectively required on Windows 11 Home).
• Hardware virtualization — Intel VT-x or AMD-V enabled in BIOS/UEFI (required by WSL2). Usually on by default.

Verify with systeminfo | findstr /C:"Hyper-V" — every "Hyper-V Requirements" line should read Yes.

1. Windows 11 system settings — 5 minutes

1.1 Explorer — show extensions, hidden files, full path

Win + E opens Explorer → View → Show → File name extensions + Hidden items. Or do it in one shot from PowerShell:

# Show extensions + hidden files
Set-ItemProperty -Path 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced' -Name HideFileExt -Value 0
Set-ItemProperty -Path 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced' -Name Hidden -Value 1
Stop-Process -Name explorer -Force

1.2 Clipboard history (Win + V)

Very useful, off by default. Settings → System → Clipboard → Clipboard history ON.

1.3 Virtual desktops

Ctrl + Win + ←/→ — switch desktops. Built-in but many newcomers don't know it. The Windows answer to macOS swipe-between-spaces.

1.4 PowerToys (optional, strongly recommended)

Microsoft's official productivity suite. One winget line:

winget install Microsoft.PowerToys --source winget --silent

Highlights: FancyZones (window tiling — the Rectangle equivalent), PowerToys Run (Alt + Space — Raycast equivalent), Keyboard Manager (key remapping).

2. winget — check the package manager

winget ships with Windows 11. Very old builds may need an update.

winget --version
# v1.x.x  ← present? you're good

Missing or stale? Microsoft Store → search "App Installer" → update. winget lives inside that package.

Automation script (optional)

Prefer to run one script instead of every step? Always download → verify SHA-256 → inspect → run.

# 1. Download
Invoke-WebRequest -Uri https://devalice.jaceclub.com/assets/windows/initial-setup/setup-windows.ps1 -OutFile setup-windows.ps1
 
# 2. Verify SHA-256
Get-FileHash setup-windows.ps1 -Algorithm SHA256
# expected: 75A9A5CC7B8804CF0808971A648B7174DADE3A5F32F2DB9C80A9783242EEEEBD
# (lowercase: 75a9a5cc7b8804cf0808971a648b7174dade3a5f32f2db9c80a9783242eeeebd)
 
# 3. Inspect
notepad setup-windows.ps1
 
# 4. Run (relax execution policy for this session only)
PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1

The script is idempotent — re-running after a partial failure is safe. It automates the winget install + Git config + SSH key creation. WSL2 install and GitHub key registration remain manual.

If you'd rather follow each step manually, continue below.

3. winget essentials — 10 minutes

3.1 Eight essentials in one line

winget install --silent --accept-source-agreements --accept-package-agreements `
  Git.Git `
  GitHub.cli `
  Microsoft.WindowsTerminal `
  Microsoft.PowerShell `
  Microsoft.VisualStudioCode `
  jdx.mise `
  BurntSushi.ripgrep.MSVC `
  junegunn.fzf

Some packages need a fresh terminal so PATH refreshes.

3.2 Verify

git --version
gh --version
pwsh --version       # PowerShell 7
code --version
mise --version
rg --version

3.3 Make Windows Terminal the default

Settings → Privacy & security → For developers → Terminal → choose Windows Terminal. Any future console launch opens in Windows Terminal.

4. WSL2 + Ubuntu — 10 minutes

If you'll do real Linux work, WSL2 is your primary tool. Node, Python, Docker — all much smoother inside WSL2.

4.1 Install

In an admin PowerShell (right-click → "Run as administrator"):

wsl --install -d Ubuntu-24.04

This single line:

1. Enables the WSL feature
2. Enables the Virtual Machine Platform
3. Sets WSL2 as the default version
4. Downloads and installs Ubuntu 24.04

Reboot once. After reboot, Ubuntu launches and asks for a username/password.

4.2 Initial cleanup

Inside Ubuntu:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl unzip

To open the current Ubuntu folder in Windows VS Code (auto-installs the WSL Remote extension):

code .

Access WSL files via \\wsl$\Ubuntu-24.04\home\<user> from Explorer. Linux file I/O is fastest inside WSL paths (/home/...). Putting code under Windows paths (/mnt/c/...) is much slower.

4.3 Verify WSL state

From PowerShell:

wsl --status
wsl --list --verbose
# NAME            STATE           VERSION
# Ubuntu-24.04    Running         2

5. Git globals + SSH — 10 minutes

WSL and Windows have independent git configs. Set both up.

5.1 Windows-side Git config (PowerShell)

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.autocrlf true   # Auto-handle Windows line endings
git config --global core.editor "code --wait"

5.2 SSH key — ed25519

ssh-keygen -t ed25519 -C "you@example.com"
# Default path: $env:USERPROFILE\.ssh\id_ed25519 (Enter to accept)
# Passphrase: optional

Start ssh-agent + add the key (admin PowerShell):

# Auto-start the service
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent
 
# Add the key
ssh-add $env:USERPROFILE\.ssh\id_ed25519

5.3 Register the public key on GitHub

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Open https://github.com/settings/ssh/new → Title: "Windows 11 (PC name)" → paste the key → Add SSH key.

5.4 gh CLI auth

gh auth login
# GitHub.com → HTTPS → Y (auth Git with GitHub credentials) → Login with a web browser

5.5 WSL-side Git config (optional, if WSL is your daily driver)

Inside Ubuntu, repeat:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
ssh-keygen -t ed25519 -C "you@example.com"
# Print the public key → register separately on GitHub (a distinct key per machine surface keeps audits clear)
cat ~/.ssh/id_ed25519.pub

Tip: You can symlink Windows's %USERPROFILE%\.ssh into WSL's ~/.ssh to share keys, but permissions often go wrong. Keeping separate keys is safer.

6. Verify — did everything install correctly?

From PowerShell:

Write-Host "--- Versions ---"
[System.Environment]::OSVersion.Version
git --version
gh --version | Select-Object -First 1
pwsh --version
wsl --list --verbose
 
Write-Host "--- GitHub auth ---"
ssh -T git@github.com 2>&1 | Select-Object -First 1
gh auth status 2>&1 | Select-Object -First 3

Expected output:

--- Versions ---
Major  Minor  Build
-----  -----  -----
   10      0  22631   (Windows 11 22H2+)
git version 2.x.x.windows.x
gh version 2.x.x
PowerShell 7.x.x
NAME            STATE           VERSION
Ubuntu-24.04    Running         2
--- GitHub auth ---
Hi <your-username>! You've successfully authenticated, ...
github.com
  ✓ Logged in to github.com account <your-username>

To verify on the WSL side, inside Ubuntu:

git --version
ssh -T git@github.com 2>&1 | head -1

7. Troubleshooting

wsl --install fails with 0x80070003 or a virtualization error

VT-x / AMD-V is disabled in BIOS. Reboot into BIOS → CPU Configuration → Virtualization Technology → Enabled → save and reboot.

winget "command not found"

App Installer is missing or very old. Microsoft Store → search "App Installer" → install/update.

PowerShell script execution blocked

.\setup-windows.ps1 : File ... cannot be loaded because running scripts is disabled on this system.

One-session bypass:

PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1

Persistent (user scope):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

git push returns "Permission denied (publickey)"

ssh-add -l                                # Is the key in the agent?
ssh -vT git@github.com 2>&1 | Select -Last 20

• ssh-agent service may have stopped → Start-Service ssh-agent
• The public key may not be on GitHub → check https://github.com/settings/keys

Time inside WSL drifts (future/past) after sleep

Common after suspend. Inside WSL:

sudo hwclock -s

winget refuses with "found multiple packages"

ID collision. Pin with --id:

winget install --id Git.Git --exact

Korean text breaks in Windows Terminal

Settings (Ctrl + ,) → that profile → Appearance → Font face → Cascadia Mono or D2Coding (any font with proper Korean coverage).

8. What's next

This guide ended at "Windows 11 can git push". After that:

• Advanced WSL2 — Docker Desktop ↔ WSL2 integration, memory caps (%USERPROFILE%\.wslconfig) — WSL tuning
• Dev tooling — language runtimes (Node · Python), editor extensions
• AI agent environment — Claude Code setup — /ai-agents/claude-code
• Concurrent Mac use — input sharing, file sync — /multi-os/input-sharing

References

• winget official
• WSL official docs
• PowerToys
• GitHub SSH key guide

Changelog

• 2026-05-12 — Initial English translation (devAlice M3 i18n seed)