Skip to main content

Set up WSL2 for documentation development

Author: Joseph Cayouette
Version: v1.0 (2025-10-22)

Applies to:

  • Windows 10 (Build 19044+)
  • Windows 11

Table of contents​

Overview​

Windows Subsystem for Linux 2 (WSL2) lets you run a full Linux environment on Windows. Use it to clone uyuni-docs and build with Podman or Docker and Task — the same path as on a Linux host.

Enable WSL2 and Virtual Machine Platform​

Open PowerShell as Administrator and run:

wsl --install

This command:

  • Enables the necessary Windows features (Microsoft-Windows-Subsystem-Linux and VirtualMachinePlatform)
  • Installs the latest Linux kernel
  • Installs Ubuntu by default

If you need to install features manually (older systems):

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Then, restart your computer.

Install a Linux distribution​

List available distributions:

wsl --list --online

Example output:

The following is a list of valid distributions that can be installed.
  Ubuntu-26.04
  Debian
  openSUSE-Leap-16.0
  openSUSE-Tumbleweed

Install your preferred distribution, for example:

wsl --install -d Ubuntu-26.04

or

wsl --install -d openSUSE-Leap-16.0

Set WSL2 as the default version​

Ensure new distributions use WSL2 by default:

wsl --set-default-version 2

To upgrade an existing one:

wsl --set-version Ubuntu-26.04 2

Accessing WSL2​

To start your Linux environment:

wsl

Or from the Start Menu, search for your distribution name (e.g., “Ubuntu”).

From within WSL, you can access your Windows filesystem at:

/mnt/c/Users/<YourUsername>/

Install the documentation toolchain​

Inside WSL2, install Podman (or Docker) and Task, then follow Container setup. You do not need a host install of Antora or Ruby.

On Ubuntu inside WSL:

sudo apt update
sudo apt install -y git podman
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Then clone uyuni-docs and run task container:build.

Integrate with VS Code​

Install the Remote - WSL extension on Windows:

code --install-extension ms-vscode-remote.remote-wsl

Then open your Linux workspace directly from VS Code:

  1. Launch VS Code.
  2. Press F1 → type WSL: Connect to WSL.
  3. Select your installed distribution.
  4. Open or clone your project folder inside the Linux environment.

This lets you edit Linux files using VS Code while executing commands natively in WSL.

Tips and maintenance​

  • List all installed distributions: 
    wsl --list --verbose
  • Update your kernel manually (if needed): 
    wsl --update
  • Restart WSL: 
    wsl --shutdown
  • Backup your WSL environment: 
    wsl --export Ubuntu-26.04 ubuntu-backup.tar

End of Guide
You now have a WSL2 environment ready to build documentation with Task and the container.