Setting Up WSL2 for Development: A Complete Guide

WSL2 (Windows Subsystem for Linux 2) runs a real Linux kernel inside Windows. Unlike WSL1, which translated Linux system calls, WSL2 uses a lightweight virtual machine with full system call compatibility. This means Docker runs natively, filesystem performance is dramatically better, and virtually every Linux tool works exactly as expected.

For developers who use Windows but work with Linux-based tooling — which is most developers — WSL2 eliminates the need to dual-boot or run a full VM. And because ConfigSync treats WSL2 as a standard Linux environment, you can sync your Mac or Linux configs directly into your WSL2 instance with no extra work.

If you have not set up WSL2 yet, the process is straightforward on Windows 10 (build 2004+) or Windows 11:

Once your distro is running, you are in a full Linux environment. Everything from here on out is standard Linux — the same commands work whether you are on bare metal Ubuntu, a cloud VM, or WSL2.

The recommended way to install Node.js in WSL2 is via nvm, which gives you version management and avoids permission issues:

The power of ConfigSync with WSL2 is pulling your existing environment from another machine. If you have been using ConfigSync on your Mac, your configs are already in the cloud. Pull them into WSL2:

WSL2 reports its platform as linux, which means ConfigSync's template conditionals handle WSL-specific paths and settings automatically:

When ConfigSync restores this file on WSL2, it evaluates the conditionals and produces a clean .zshrc with only the Linux-specific sections. Your macOS-specific config is stripped out automatically, so there are no broken paths or missing commands.

ConfigSync maintains a mapping table that translates packages across package managers. Here is how common development packages map from Homebrew to apt:

Note that GUI applications like VS Code are skipped on WSL2 because they run on the Windows side. The recommended approach is to install VS Code on Windows and use the Remote WSL extension to edit files inside your WSL2 environment.

WSL2 is excellent, but there are a few things to watch out for when setting up your development environment:

SSH Agent Forwarding

If you use SSH keys on the Windows side (for example, in Windows Terminal or PuTTY), you may want to forward the SSH agent into WSL2 rather than maintaining separate keys. Tools like npiperelay or wsl2-ssh-agent bridge the Windows SSH agent into WSL2. Alternatively, ConfigSync can restore your SSH keys directly into WSL2 so you do not need forwarding at all.

File System Performance

Always keep your project files inside the WSL2 filesystem (under /home/username/), not on the Windows filesystem (under /mnt/c/). Accessing Windows files from WSL2 is significantly slower due to the 9P protocol bridge. ConfigSync restores files to your Linux home directory by default, so this is handled automatically.

VS Code Remote WSL

Install VS Code on Windows, then install the "WSL" extension. When you run code . from inside WSL2, it opens VS Code on Windows with a remote connection into your WSL2 environment. Your ConfigSync VS Code settings apply to the WSL2 side automatically.

ConfigSync treats your WSL2 instance and your Windows environment as separate machines. This is intentional — they have different package managers, different paths, and often different needs. You can push and pull independently:

This separation means you can customize your WSL2 environment independently — adding Linux-specific tools or configs — without affecting your macOS or Windows setup. Each machine is a first-class citizen in ConfigSync.

The beauty of WSL2 is that it is just Linux. ConfigSync does not need any special WSL2 support because everything works exactly as it would on a native Linux machine. Your zsh config, git settings, SSH keys, vim setup, and project environment variables all work identically. If you are already using ConfigSync on macOS or Linux, adding a WSL2 machine to your sync is effortless.

Install ConfigSync, pull your environment, and start coding. WSL2 handles the rest.