I recently had to instruct a bunch of users on how to set up the WSL2 (Windows Subsystem for Linux v2) on Windows and opted to document the process here. These instructions are relevant as of 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 directly from Windows without necessitating a “virtualized” or “containerized” environment (e.g. VirtualBox, Docker, etc.) or emulator.
WSL is important for developers and IT users because a lot of open source software, especially as related to the web and/or web development, is designed exclusively for linux and/or unix systems. This normally hasn’t presented a problem to MacOS users because MacOS is unix-based, but this has presented an issue to Windows users for years.
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
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
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
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
For example, you can list the files + folders in your user’s Windows Documents directory via the command:
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:
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.