The Ultimate Guide to WSL2 and Ubuntu: Updates, Managing APT Phasing, and Dev Optimizations

When updating WSL2 and the Ubuntu distribution on Windows 11, it is essential to distinguish between updating the underlying WSL2 engine/Linux kernel (executed via PowerShell or Command Prompt in Windows) and updating the internal software packages within the Linux distribution (executed inside the Ubuntu terminal).

PowerShell / Command Prompt Commands (on Windows 11)

These commands should be executed by opening PowerShell or CMD (preferably as Administrator) in Windows:

Ubuntu Terminal Commands (inside WSL2)

These commands are executed directly inside the Ubuntu shell (e.g., by typing wsl or opening the Ubuntu app in Windows):

Pro Tip for Daily Updates: You can combine the two primary Ubuntu commands into a single line to run everything at once:

sudo apt update && sudo apt upgrade -y

Phasing: What It Is and How It Works

Phased updates (or staged rollouts) in Ubuntu is a safety feature introduced by Canonical to prevent buggy updates from breaking every user's computer at the same time.

Instead of releasing a new package update to all users simultaneously, Ubuntu rolls it out in gradual "waves".

The system works across four key aspects:

01. The Lottery Mechanism (Client Side)

When developers publish a non-security update, they assign it an initial percentage threshold (typically 10%).

• When your PC runs apt update, it calculates a random number between 1 and 100 based on your local Machine ID (a unique hardware identifier) combined with the package name and version.

• No telemetry or data is sent to Canonical; the calculation happens entirely on your local machine to preserve privacy.

• If the generated number is less than or equal to the current release percentage, the package is installed. Otherwise, APT shows the warning message: "Not upgrading yet due to phasing".

02. Crash Monitoring and Progression (Server Side)

Every 6 hours, Ubuntu servers aggregate automated crash reports from machines that received the initial update (the first 10% wave).

• If no issues are detected: The rollout percentage increases by 10%. In about 54 hours (just over 2 days), the update reaches 100% and becomes available to everyone.

• If a critical bug is detected: The rollout is immediately halted (dropped back to 0%). This ensures the bug only affected a small fraction of users, allowing developers to patch it before it causes widespread damage.

03. What Exceeds Phasing?

Not all packages undergo this process. Critical security updates always bypass phased updates and are deployed immediately across all systems to patch vulnerabilities.

04. Disabling Phasing Permanently

If you manage servers that require perfectly synchronized packages or prefer not to have pending updates, you can disable phased updates by creating an APT configuration file:

1. Open your terminal and create the file:

sudo nano /etc/apt/apt.conf.d/99phased-updates

1. Add the following line to the file:

APT::Get::Always-Include-Phased-Updates "true";

1. Save and close (press Ctrl+O then Ctrl+X in nano). From this point on, apt upgrade will bypass phasing and download all pending updates immediately.

On a desktop environment running WSL2 (Windows Subsystem for Linux), the context differs significantly from a production server. Because WSL2 is a local development and testing environment inside Windows, bypassing phasing carries minimal risk.

Why you can safely bypass phasing on WSL2:

• Easy Recovery: If an unstable package causes issues inside WSL2, you won't break your main host OS (Windows 11/10 continues running normally).

• Zero Boot Downtime: In case of a critical instance breakdown, you can back up your home folder from Windows or spin up a fresh distro instance in seconds.

• WSL-Specific Packages: Essential utilities (like python3-software-properties and software-properties-common) handle external software repositories (PPAs). Keeping them up to date avoids compatibility issues with newer dev tools.

Making It Permanent on WSL2

To prevent this warning from appearing in your terminal, run this single command inside your Ubuntu instance to automate the configuration:

echo 'APT::Get::Always-Include-Phased-Updates "true";' | sudo tee /etc/apt/apt.conf.d/99phased-updates

Once executed, simply run sudo apt update && sudo apt upgrade to align all packages instantly.

05. Advanced Optimizations for the WSL2 Development Stack

Bypassing phased updates eliminates terminal warnings, but additional performance tweaks are essential to achieve near-native execution speeds and eliminate host OS conflicts.

1. Docker: Do Not Install Docker Engine Directly inside WSL2

Avoid installing Docker Engine directly inside the Ubuntu instance via apt. Doing so leads to network conflicts and kernel instabilities within WSL.

• The Correct Way: Install Docker Desktop on Windows. • Integration: Open Docker Desktop settings, navigate to Settings > Resources > WSL Integration, and enable your Ubuntu distribution. Docker will map binaries and sockets automatically into Linux, enabling the docker CLI directly from your Ubuntu terminal with optimal performance.

2. Python and Node.js: Manage Versions Without sudo

Avoid installing global Node.js packages or Python modules using sudo apt install. This practice risks corrupting system-level dependencies.

• For Node.js: Use fnm (Fast Node Manager) or nvm. These version managers let you switch between Node versions (e.g., LTS vs. Latest) seamlessly without root permissions. • For Python: Use pyenv for Python version management alongside poetry or venv to isolate project dependencies.

3. File System Performance (The Golden Rule)

WSL2 file system performance degrades significantly when crossing OS boundaries.

• DO: Store all project files inside the Linux home directory (e.g., /home/your-username/projects/). • DO: Use VS Code on Windows paired with the WSL extension. It will open your Linux-hosted projects at native performance. • DON'T: Never run cd /mnt/c/Users/... to develop projects stored on the Windows C: drive. Accessing files through /mnt/c/ is extremely slow for Node and Python tooling.

4. Memory Management (.wslconfig)

By default, WSL2 can consume up to 50% (or more) of your total host RAM. Running heavy Docker containers or intensive scripts can cause Windows to lag.

You can cap resource usage by creating a .wslconfig file in your Windows user profile folder (C:\Users\YourUsername\.wslconfig):

[wsl2]
memory=8GB   # Cap RAM allocated to WSL2 (e.g., 8GB or 16GB)
processors=4 # Cap CPU cores allocated to WSL2
guiApplications=false # Disable Linux GUI apps if you only use the CLI

After saving the file, restart WSL2 from Windows PowerShell:

wsl --shutdown