Install WSL for Development and Fix Common Problems on Windows

WSL is one of the easiest ways to get a comfortable Linux development shell on Windows, but the first setup still has a few sneaky corners. This guide covers the bits worth fixing early.

WSL removes a lot of friction when you want Linux tooling without leaving Windows behind. The installation is short, but a few follow-up steps make it much more pleasant for real development work, especially if you use Git, .NET, or large local project folders.

Installation

Install WSL

Run the following command to install WSL:

wsl --install

Restart Windows to complete the setup. When WSL starts for the first time, it will ask you to create a Linux username and password for your default account.

Update packages

Once the distro is ready, update the package list and install the latest updates:

sudo apt update && sudo apt upgrade -y

Install build tools and locale support

Run the following commands to install build tools:

sudo apt install -y build-essential pkg-config libssl-dev locales unzip
sudo locale-gen en_US.UTF-8

That is enough for many common CLI tools and source builds. If you later hit a package that still complains: WSL has invited you into the traditional Linux pastime of installing one more dependency.

Install the .NET SDK

If you use .NET inside WSL, start with Microsoft's distro-specific instructions because the package feed can vary by Ubuntu version:

Install .NET on Ubuntu

On an Ubuntu-based WSL image, the final install step commonly looks like this:

sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

Then verify the SDK is available:

dotnet --info

Open your WSL folder in File Explorer

To open your WSL project in Windows File Explorer, use the following command:

explorer.exe .

That is a handy way to move between terminal work and GUI tools without memorising the hidden network path to your distro.

Git Setup

If you want Git commands inside WSL to reuse the credentials you already signed into on Windows, set that up early. It saves a lot of repetitive prompts later.

Install Git on Windows

Ensure the latest version of Git is installed on Windows.

Reuse Windows credentials from WSL

Then configure Git Credential Manager from the Linux side. This assumes Git for Windows is installed and reasonably current.

git config --global credential.helper "/mnt/c/Program Files/Git/mingw64/bin/git-credential-manager.exe"

If Git still refuses to use the saved credentials, close all WSL windows and shut it down from the Windows side:

wsl --shutdown

Reopen WSL after shutting it down.

Troubleshooting

Reclaim space from a growing WSL virtual disk

WSL disks tend to grow quietly and stay large even after you delete files. Before compacting the virtual disk from Windows, clean up what you can from inside Linux:

sudo apt clean
sudo apt autoremove -y
sudo fstrim -v -a

If you use Docker, large package caches, or temporary build folders inside WSL, clean those up first as well. Compacting works better after the filesystem has already released as much space as possible.

If the Optimize-VHD PowerShell command is not available, enable Hyper-V management tools from an elevated PowerShell window:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Windows may ask for a restart. After that, run this elevated PowerShell script to compact every Store-managed WSL disk it can find:

function Compress-WSLDisks {
  $disks = Get-ChildItem -Path "$env:LOCALAPPDATA\Packages\*\LocalState\ext4.vhdx" -ErrorAction SilentlyContinue

  if (-not $disks) {
    Write-Host 'No Store-managed WSL disks were found.'
    return
  }

  wsl --shutdown

  foreach ($disk in $disks) {
    $before = [math]::Round($disk.Length / 1GB, 2)
    Write-Host "Compacting $($disk.FullName)"
    Write-Host "Before: $before GB"

    Optimize-VHD -Path $disk.FullName -Mode Full

    $updatedDisk = Get-Item -LiteralPath $disk.FullName
    $after = [math]::Round($updatedDisk.Length / 1GB, 2)
    Write-Host "After:  $after GB"
  }
}

Compress-WSLDisks

This script targets the default Store-backed disk location. If you imported a distro to a custom path, compact that .vhdx file directly instead.