# WSL2 Windows Development Setup A complete setup for software development on **Windows 11** that puts the bulk of the toolchain inside **Ubuntu 26.04 LTS running in WSL2**. The Windows side stays small: winget, Windows Terminal, Git for Windows, VS Code, and Claude Code. The Linux side does everything else. This works identically on **ARM64 (Snapdragon, Surface Pro 11) and x64 (Intel/AMD)** Windows 11 hosts. On an ARM64 host, WSL2 runs an `arm64` Ubuntu guest natively — no cross-architecture emulation. This is one of two Windows paths in the [[Windows 11 Development Setup]] index. The other is the [[Native Windows Development Setup|fully-native path]]; they don't conflict and can coexist. ## Where to start Everyone starts here: - [[General_Development_Windows_WSL2_Setup|General Setup]] — install winget, Windows Terminal, VS Code, Claude Code on the Windows side; install WSL2 and Ubuntu 26.04; hand off to the Ubuntu language guides That single guide is the only WSL2-specific document. Once you're inside Ubuntu, **everything language-specific is the existing Ubuntu guide**, unchanged: - [[Python_Development_Ubuntu_Setup|Python]] — uv, ruff, mypy, ipython - [[C_Development_Ubuntu_Setup|C]] — gcc/clang, cmake, ninja, gdb, valgrind, raylib - [[Ruby_Development_Ubuntu_Setup|Ruby]] — rv, Bundler - [[Go_Development_Ubuntu_Setup|Go]] — go, golangci-lint, gopls - [[Rust_Development_Ubuntu_Setup|Rust]] — rustup, cargo tooling ## What you'll end up with A two-layer setup: - **Windows side (small):** winget for installing Windows apps; Windows Terminal as the terminal application; Git for Windows so the Windows-side tools can clone repos too; VS Code with the WSL extension; Claude Code (native Windows binary) for AI work that benefits from sitting outside the Linux guest. - **Linux side (everything else):** Ubuntu 26.04 LTS inside WSL2, set up exactly per the [[General_Development_Ubuntu_Setup|Ubuntu General Setup]]. Ghostty is replaced by Windows Terminal as the outer shell; everything else — bash, Starship, ble.sh, apt, the language toolchains — is unchanged. VS Code uses its **WSL Remote** extension to bridge the two: you open a project from inside Ubuntu (`code .`), and VS Code launches a Windows-side editor wired into the Ubuntu file system, Ubuntu shell, and Ubuntu Claude Code installation. The integrated terminal is your Ubuntu bash with the Starship prompt. To you, it looks like one cohesive environment. ## Why this is the recommended path The Ubuntu toolchain ([[General_Development_Ubuntu_Setup]]) is built around apt, bash, and POSIX tools that match what Linux servers, CI runners, and Docker images use in production. Putting it inside WSL2 means: 1. **Your dev machine matches your runtime.** Less "works on my machine, breaks in CI" friction. 2. **One guide, two architectures.** The Ubuntu guide already supports both `amd64` and `arm64`. WSL2 inherits the host's architecture, so an ARM64 Windows 11 machine runs the arm64 Ubuntu image with no extra steps. 3. **You don't lose Windows.** Windows-side apps (VS Code, browsers, Slack, Office) keep working normally. WSL2 only owns the dev environment. 4. **Cross-platform compile is easy.** Building Linux containers, testing Docker images, and running Linux-only tools (perf, eBPF, strace) just works. ## Companion files The few Windows-side config files this path needs: - [[_resources/configs/windows-terminal-settings.json|Windows Terminal settings]] (in the Native path's resources folder — both paths use the same terminal) - [[_resources/configs/vscode-settings.json|VS Code settings]] (same — VS Code is a Windows-side app even when editing Linux files) Linux-side configs (Ghostty replaced by Windows Terminal, plus Starship, VS Code's Linux settings, bash) live in the [[Ubuntu Linux Development Setup|Ubuntu guides]]. ## Related notes - [[Windows 11 Development Setup]] — the top-level Windows index and path picker - [[Native Windows Development Setup]] — the Windows-only alternative - [[Ubuntu Linux Development Setup]] — the language guides you'll hand off to - [[Mac Tahoe Development Setup]] — the macOS counterpart - [[Software Development Home]] — index of all platform setups