A WSL distribution designed for easy 'plug and play' usage with Containerlab.
Important
WSL 2.4.4 is required to use this distribution. It is currently in pre-release, meaning you must manually install it.
| OS | Supported | VM-based NOSes |
|---|---|---|
| Windows 10 | Yes | No |
| Windows 11 | Yes | Yes |
We recommend using Windows Terminal for the best experience:
- Windows 11 users: Windows Terminal is installed by default.
- Windows 10 users: Download Windows Terminal from the Microsoft Store.
Ensure WSL2.4.4 or newer is installed.
- Download the
.wslfile from the releases page. - Double click the
.wslfile to install. - Open 'Containerlab' from the start menu, or execute
wsl -d Containerlab - Complete the interactive shell selection.
- If you have Docker Desktop installed. See Docker Desktop.
- Done! you can start labbing. (see DevPod for a great way to lab).
Note
Default credentials are clab:clab
This distro makes use of WSL2, which requires that virtualization is enabled in your UEFI/BIOS.
This may appear as something called 'SVM (AMD-V)' or 'Intel VT-x' depending on your processor.
Open PowerShell and type:
wsl --installRestart your PC, and WSL2 should be installed.
Tip
Newer versions of Windows 10 allow usage of wsl --install, just like with Windows 11.
Instructions are from 'Manual installation steps for older versions of WSL'.
Open an elevated PowerShell window (as administrator) and paste the following two commands:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartAt this point restart your computer. After it has rebooted download the latest WSL2 kernel. Download link.
Follow the installation wizard. After completion finally set WSL2 as the default version of WSL.
In PowerShell or command prompt paste the following:
wsl --set-default-version 2Run wsl --version in PowerShell or command prompt to ensure WSL2 is enabled. The WSL version number should be 2.4.4.0 or higher.
PS C:\Users\Kaelem> wsl --version
WSL version: 2.4.4.0
Kernel version: 5.15.167.4-1
WSLg version: 1.0.65
MSRDC version: 1.2.5620
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.19044.5131Ensure WSL is enabled and you have WSL 2.4.4 or newer. See the version check instructions.
-
Download the
.wslfile from the latest release. -
Double click the
.wslfile. This will install the distribution.You may see an error that nested virtualization is not supported. See vrnetlab.
-
From the start menu you can launch the distribution from a new 'Containerlab' shortcut which has been added.
or in PowerShell/cmd you can execute:
wsl -d Containerlab -
On first launch you will be presented with an interactive menu to select what shell and prompt you would like.
This menu will give you options of
zsh,bash(with a fancy two-line prompt) orbashwith the default prompt.You will also be presented with the choice to have the Fira Code nerd font automatically installed on your system. We recommend you install this font (especially if using
zshas your shell of choice).Finally at the end SSH keys will be copied from your Windows host into Containerlab WSL to enable passwordless SSH. This is an integral step for DevPod usage.
If no SSH keys are found on your machine, an RSA keypair will be automatically generated.
To run the setup again, execute
/etc/oobe.shinside Containerlab WSL.
Important
After installation, close and reopen Windows Terminal to ensure proper font rendering and appearance settings have been applied correctly.
This step is necessary for the terminal to recognize and use the newly installed WSL distribution's display configurations.
-
You can open Containerlab WSL in the following ways:
- From the profile in Windows Terminal (recommended).
- From the shortcut in the start menu.
- Executing
wsl -d Containerlabin PowerShell or command prompt.
Note
Opening WSL via the shortcut or wsl -d Containerlab will not
open in our custom Windows Terminal profile. The customised
appearance settings will not be functional in this case.
Important
This feature is only supported on Windows 11.
You can run vrnetlab (VM-based) nodes on top of WSL2 and use them in containerlab. Containerlab WSL is already configured so that nested virtualization is enabled on the distro side.
To use vrnetlab nodes on Containerlab WSL you must ensure that nested virtualization is enabled globally in WSL.
-
You can do this by opening the 'WSL Settings' app, going to the 'Optional features' tab and ensuring 'Enable nested virtualization' is enabled.
If you don't get any errors during installation or distro bootup saying that 'Nested virtualization is not supported on this machine.' You should be good to go.
See the containerlab user manual for more information about vrnetlab.
WSL2 runs as a VM. By default allocated resources are:
| Resource | Default value | Description |
|---|---|---|
| vCPU | Logical thread count | If your processor has 8 cores and 16 threads, WSL2 will assign 16 threads to the WSL VM |
| RAM | 50% of system memory | If you have 32Gb of RAM on your system, WSL will allocate 16Gb to the WSL VM. |
| Disk | 1Tb | Regardless of disk size, the WSL VM will have a VHD with a maximum size of 1Tb. The disk is thin/sparse provisioned. |
Despite the fairly generous resource allocation by default. WSL2 will not use 100% of the assigned resources.
If you have Docker desktop installed. You must ensure the integration with the Containerlab WSL distro is disabled, otherwise Containerlab will not work inside Containerlab WSL.
- Open Docker Desktop window and go to settings (gear icon on the title bar)
- Under the 'Resources tab, enter the 'WSL integration' page
- Ensure 'Containerlab' has integration disabled
DevPod is an awesome tool which can let us easily run labs which take advantage of Devcontainers, which overall can give a 'one-click' lab experience. It's like running the codespaces labs but on your local machine.
Check out this video for more info.
Containerlab WSL was designed to support this lab experience out of the box. Just remember the following consideration:
- When using DevPod, ensure Containerlab WSL is started (it does not automatically launch on Windows startup), you should leave the terminal window with Containerlab WSL open in the background.
A one-time configuration step is required. You must setup a provider in DevPod. For Containerlab WSL, create the SSH provider with the following values:
| Field | Value |
|---|---|
| Host | clab@localhost |
| Port | 2222 |
You can leave the other settings as the default values. See the screenshot below.
After configuring the provider, you are done! You can now use one-click labs you see with the DevPod button, or configure the lab workspaces yourself.
Development should be performed from another WSL distribution.
Clone the repository and build using the build script (you may have to chmod +x the script)
./build.shThis will place clab.wsl in C:\temp. Doubleclick to install the distribution.
- From inside a WSL distro Build the container:
docker build . --tag ghcr.io/kaelemc/clab-wsl-debian- Run it and export the filesystem to a
.wsl.file:
docker run -t --name wsl_export ghcr.io/kaelemc/clab-wsl-debian ls /
docker export wsl_export > /mnt/c/temp/clab.wslCreate the 'temp' directory on your C: drive if it doesn't exist.
Remove the container to ease rebuilding:
docker rm wsl_export- Use it
In your windows filesystem at C:\temp should be a file clab.wsl, double click to install. or use:
wsl --install --from-file clab.wslUninstall Containerlab WSL using the following command in PowerShell/command prompt:
wsl --unregister ContainerlabEnsure uninstallation by checking installed distros:
wsl -l -v