How to set up Windows Subsystem for Linux (WSL2) and Ubuntu on Windows 10

I recently helped a few users get running with WSL2 (Windows Subsystem for Linux v2) and decided to document the process here.

These instructions current to the time of writing: 2021-02-15.

Introducing the WSL

The WSL is a “compatibility layer” introduced in Windows 10 + Windows Server 2019 that enables PC’s to natively run binary executables that were created for linux.

Microsoft’s introduction of the WSL enables developers to effectively write and execute software and scripts intended for linux/unix environments from within Windows without a heavier “virtualized” or “containerized” environment such as VirtualBox, Docker, etc. or an emulator.

WSL is significant because a lot of open source software is written exclusively for linux/unix systems, especially if its related to the Internet and/or web development.

Part of the popularity of MacOS systems among developers is that MacOS is unix-based.

Until WSL was released Windows users always had to sacrafice something to achieve a productive linux-compatible developer workflow.

Let’s get started setting up WSL2 on Windows…

Open the Microsoft Instructions

Open a tab with the official Microsoft instructions for WSL2: https://docs.microsoft.com/en-us/windows/wsl/install-win10

This guide encourages you to follow the “Manual Installation Steps” (so scroll down to that heading).

Opening PowerShell as Administrator

Microsoft’s instructions require you to use the Windows PowerShell as an Administrator but don’t explain how to do this.

As a prerequisite, ensure that your Windows user actually has Administrator access to your system! If you own your computer and set it up yourself then this is very likely to be the case. Otherwise you may need to talk to your IT administrator.

Start by opening the Start Menu. Type “PowerShell” so the menu finds it.

Instead of hitting enter or clicking the result to open it, use your mouse to right click the PowerShell app and choose “Run as Administrator” from the right-click context menu.

Follow Microsoft’s Instructions for WSL2

Follow Microsoft’s “Manual Installation Steps” from the above “Microsoft Instructions” link.

Be sure to perform the step that activates WSL2 (vs. WSL1).

When you get to Step 6 (“Install your Linux distribution of choice”), unless you have a specific need for a different linux distribution (or “distro”), I recommend choosing Ubuntu 20.04 LTS from the Microsoft Store.

If there is an even more recent Ubuntu LTS (LTS = Long Term Support) version available than 20.04 by the time you’re reading this guide, choose whatever is most recent.

Ubuntu is the most popular linux distribution (or “flavour” of linux). It is based upon the wonderful and rock-solid Debian linux distribution.

NOTE: Be sure to read the next section before you set up a username and password in your new linux environment.

You can now run Ubuntu (or whatever distro you chose to install) from Windows by opening the start menu, typing it’s name (e.g. “Ubuntu”), and then opening the app. From this point forward, I will assume that you have installed Ubuntu.

Set Up Your Linux Distro

It is important to complete the following steps.

Username and Password

When the WSL2 terminal (e.g. Ubuntu) first runs, you will be prompted to set up a username and password.

User accounts and passwords under the WSL are different than Windows.

Choose a username that is lowercase and doesn’t have any spaces or special characters in it (even if your Windows username does).

Linux and unix systems aren’t particularly friendly towards usernames with spaces or special characters in them (with the exception of underscores). Save yourself a world of future headaches by choosing a linux-and-unix-friendly username comprised of lowercase letters and/or numbers and/or underscore(s).

Note that linux/unix systems are generally supportive of usernames with dashes and dots as well but for various other reasons related to compatibility with other software and systems, I wouldn’t recommend you create a username that includes these characters either.

Run system updates

Ubuntu uses apt (“Advanced Package Tool”) to manage software packages.

If you chose a different linux distro, you may have to use a different package manager (you can search out what is appropriate for your distro). For example, CentOS uses the yum package manager by default.

Run the following command to sync with the update servers:

sudo apt update

The sudo command tells linux to run the following command (apt update in this case) as the root (Administrator) user. If sudo has not been used in a while, it will prompt you to enter your user’s password as a security measure.

Next run the following command to upgrade all packages:

sudo apt upgrade

Depending on what needs to be upgraded, you may be prompted to confirm before proceeding. If this happens, you can respond by inputting y for “yes” and then hitting enter.

After running the update + upgrade sequence, it can be helpful to run the following command to clean up any unused packages and free up space:

sudo apt autoremove

You will want to run the above sequence of update + upgrade + autoremove commands from time to time to ensure that your linux system stays up to date.

Familiarize Yourself with Linux and WSL2

If you haven’t used linux before, search for “basic linux commands” and familiarize yourself with them.

You should at least be able to show your current working directory (pwd), change (cd) to another directory, list files/folders (ls), as well as open/edit/save plaintext files with a command-line-based text editor like nano or vim.

You can read and access files on the “Windows side” of your system from the Ubuntu terminal. For example the C:\ drive on Windows can be accessed at the path /mnt/c.

For example, you can list the files + folders in your user’s Windows Documents directory via the command:

ls /mnt/c/Users/WINDOWS_USERNAME/Documents/

Replace WINDOWS_USERNAME with your Windows username. If your Windows username has spaces or special characters in it, you will need to enclose the path in quotes as follows:

ls "/mnt/c/Users/WINDOWS_USERNAME/Documents/"

You can read and access files on the “WSL side” of your system from Windows by accessing \\wsl$ from File Explorer.

If you plan to create files and/or folders on Windows from within the WSL (or vice versa), please do some research first and ensure you are familiar with various potential implications especially as related to permissions.

Development on Windows

If you are a developer and have Visual Studio Code (VSCode) installed on Windows, you can use it to open and work with projects that are saved within the WSL side of your system.

Refer to this URL and follow the instructions to set up this functionality: https://code.visualstudio.com/docs/remote/wsl-tutorial

In the Ubuntu Terminal, suppose you have a given project folder (e.g. as cloned from a git repo). Navigate to the folder on linux (e.g. cd /path/to/project_folder) and then run the command code .. This will initiate a special process where the project will open in VSCode on Windows using the project files from WSL.

This arrangement is hugely useful for web development projects that are intended for deployment on linux-based servers or cloud environments. You can run the full development stack (including any development servers such as database servers, web servers, etc.) from within the WSL, and then write code in VSCode running on the Windows side of things.

If you use Docker, you can also set it up to work with the WSL. After setting up the WSL (ideally WSL should be set up first), take note of the WSL and Windows-related options when running the Docker installer app from Windows.