GitHub

WSL 2

Learn to install WSL, an easy Linux environment on Windows, and configure it for code development.

It is possible to have multiple distributions on WSL.

Installing WSL

LogoGitHub - codeedu/wsl2-docker-quickstart: Guia rápido do WSL2 + DockerGitHub
# As administrator
# If the flag `--no-distribution` is not specified, Ubuntu will be automatically installed
wsl --install

After reboot, updates are applied, and the terminal is automatically started to continue Ubuntu installation on WSL.

It will ask you to setup your Unix user and password.

If everything went well running wsl in terminal will open the connection to Ubuntu.

Installing more instances

Import the image

Download the tar.gz or .gz file of a wsl ubuntu image.

Then create a folder where the new instance will be used, and run the command to import it.

wsl --import <distribution-name> <installation-folder> <wsl2-tar-file-path>

Where:

  • <distribution-name>: Is the name you want to give this new Linux instance.

  • <installation-folder>: Is the folder you want to install the new Linux instance.

  • <wsl2-tar-file-path>: Is the path to the downloaded .tar.gz file.

wsl --import ubuntu-another "C:\Ubuntu-Another" "C:\downloaded\ubuntu-jammy-wsl-amd64-wsl.rootfs.tar.gz"

After the import verify the installation:

wsl -l -v

Imported distributions will log as root user. Manually create another user.

Bring up the instance with wsl -d <distro-name>.

Setup new user

useradd -m -G sudo -s /bin/bash "<username>"
passwd "<username>"

Set this user as the default login user by creating or editing /etc/wsl.conf.

[user]
default=<username>

Setup instance hostname

Also add to the /etc/wsl.conf a new hostname so that the instance's hostname reflect the distro name.

[network]
hostname = <distro-name>
generateHosts = false

After update the /etc/hosts and add the new hostname with 127.0.0.1.

...
127.0.0.1    <distro-name>
...

Update & Upgrade

After, shutdown the instance with wsl --terminate <distro-name>. Log with the created user and finish the installation with:

sudo apt update
sudo apt upgrade

Add new terminal to Windows terminals

Create a new terminal to automatically open the new instance, with the following command line:

Command Line
C:\Windows\system32\wsl.exe -d <distro-name>

Using WSL

When using your WSL, do NOT run things on /mnt/c/* because it will lose performance.

Accessing Windows files from inside Linux is possible by accessing from /mnt/c.

On Windows the Linux filesystem is basically a network folder as \\wsl$.

Commands

Command
Description

wsl

Start the default distribution.

wsl -l -v

List all distributions with detailed information.

wsl --shutdown

Shutdown ALL distributions.

wsl -d <distro-name>

Connect to a specific distribution, in case you have more than one.

wsl --terminate <distro-name>

Shutdown specific distribution.

wsl --manage <distro-name> --move <new-location>

Move the distribution to a new location.

wsl --set-default <distro-name>

Sets the distribution as the default. Will have a * beside their name.

wsl --unregister <distro-name>

Unregisters the distribution and deletes the root filesystem.

wsl --help

Show all wsl options and arguments.

Configuring WSL

.wslconfig vs wsl.conf

LogoAdvanced settings configuration in WSLMicrosoftLearn
WSL config options

The .wslconfig is a global configuration file that applies configuration to ALL the distros.

  • This file is not automatically created.

  • Must be placed to your Windows User root folder. (%UserProfile% or C:\Users\<UserName>)

  • WSL will detect the existence of this file every time it is initiated. If the file is incorrect, WSL will initiate without the specified configurations.

If you want to setup configurations for specific distros then use the wsl.conf file.

  • You will place this file in /etc folder of the desired distribution. (/etc/wsl.conf)

Auto size reduction of .vhdx file

Through .wslconfig

The WSL2 virtual disk is a vhdx file that grows as you use your linux distro. If you exclude files, the disk will not shrink automatically. (vhdx always grows)

To make it auto reduce, active the sparse mode of WSL2 on the .wslconfig. (Only for future created virtual disks)

.wslconfig
[wsl2]
sparseVhd=true

# Or

[experimental]
sparseVhd=true

Don't forget to restart the distro after the changes.

Manually setup the distro

For virtual disks that were already created you can convert them with:

wsl --shutdown
wsl --manage <distro-name> --set-sparse true

Other ways (wslcompact)

If even after that the disk size does not decrease, you can manually shrink with this third-party tool.

LogoGitHub - okibcn/wslcompact: Compacts the size of the ever-growing WSL vhdx images.GitHub
wslcompact
wslcompact -c <distro-name>

Other ways (optimize-vhd)

May require Hyper-V resource installation.

LogoReclaim WSL2 disk space after setting it to sparseSuper User

Limiting WSL resource consumption

.wslconfig or wsl.conf
[wsl2]
memory=4GB
processors=4
swap=1GB

After changes on this file don't forget to wsl --terminal <distro-name>.

Configure .bashrc

Show current git branch in terminal

.bashrc
# Show current git branch in terminal
parse_git_branch() {
   git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\[\033[33m\]$(parse_git_branch)\[\033[00m\]\$ '

Configure Hostname

Configure the WSL instance hostname to reflect the <distro-name> given. This will make easier to identify which instance is running in the terminal, and it is not supposed to have any impact.

See here how to configure Setup instance hostname.

Setup as your Dev space

Your code project would stay inside Linux, but you will code from Windows.

Before openning projects inside WSL in VSCode, make sure you have the Remote Development plugin installed in VSCode.

Backing up & Restore WSL

.vhdx file

You can find the .vhdx file, which is the virtual machine hard drive file here:

%LocalAppData%\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState

You could save this entire file to backup the entire Linux.

If you format your computer, on your new install:

  • Install wsl again.

  • Configure same user and password (maybe not needed).

  • Shutdown the Linux virtual machine.

  • Substitute the .vhdx file with the backup one.

PreviousNginx

Last updated