WSL Tutorial

The Windows Subsytem for Linux runs native Linux tools in a virtual machine integrated with on Windows. It includes everything in a regular Ubuntu Linux install.

WSL Background

The Windows Subsystem for Linux runs an Ubuntu Linux virtual machine. Make sure you have Windows 10 version 1903, Build 18362.1049 or higher in order to use WSL 2. Instructions for how to check your Windows version.

Some software requires WSL 2 (not WSL 1) to work correctly, for example end-to-end testing of a client-side dynamic pages app using a headless browser.

Many WSL features are better supported in Windows 11. Upgrading to Windows 11 may save some complications later on in EECS 485, but it is not required at this time.

Install WSL

Follow the instructions from Microsoft to install WSL 2. If you have not set up WSL before, follow all instructions and choose the latest version of Ubuntu for your Linux distribution.

If you already have an older version of Ubuntu installed, go to the “Upgrade version from WSL 1 to WSL 2” section. Ubuntu 20.04 or newer is required.

Check Your Installation

Start a Windows PowerShell. Verify that you are using WSL 2.

$ wsl -l -v
  NAME                   STATE           VERSION
*  Ubuntu-20.04           Running         2

If you cannot update to WSL 2 and you have confirmed your Windows Version is correct, try downloading the WSL 2 Linux Kernel and updating it manually. You can find instructions from Microsoft here.

Start a Bash shell (not a Windows PowerShell).

ubuntu shell in windows search bar results

An Ubuntu Bash shell is a terminal that looks like this:

screenshot of an ubuntu bash shell

You can now use Ubuntu Linux tools, including the apt-get package manager.

$ sudo apt-get update
$ sudo apt-get install python3 python3-pip python3-venv python3-wheel python3-setuptools git tree default-jre

Optionally, install your favorite editor and make it the default for this login session by setting the $EDITOR environment variable. Vim should be installed already.

$ sudo apt-get install emacs-nox
$ export EDITOR=emacs

If you’re using VS Code, you will have to install it first on the Windows side (not through WSL). You can find the download link for VS Code here. Follow instructions and read more about the interaction between VS Code and WSL on the VS Code docs. After following the instructions, you can open VS Code directly from any folder through WSL by doing the following:

$ code .

Where are my files?!

You now have two file systems: one on the Windows machine and another inside the Linux virtual machine (WSL).

From WSL, you can see your Windows files like this:

$ ls /mnt/c/Users/awdeorio/Desktop/
$ ls /mnt/c/Users/awdeorio/Documents/

From WSL, you can see your Linux files like this:

$ ls /home/awdeorio

If you’d like to interact with your Linux files using the Windows File Explorer, you can open the Windows File Explorer from the WSL command line. This will open the folder \\wsl$\Ubuntu\home\awdeorio in File Explorer.

$ pwd
$ explorer.exe .

A second option is to open Windows File Explorer and navigate directly to \\wsl$ in the search bar.


Avoid these common WSL pitfalls.

Spaces in path

Avoid spaces in any part of your project directory path. Some Linux programs do not support spaces in file paths.

Bad Example Good Example
/home/awdeorio/src/EECS 485/p1-insta485-static /home/awdeorio/src/eecs485/p1-insta485-static

Network file share

Avoid project directories starting with /mnt/c/. A directory shared between Windows and Linux (/mnt/c/whatever/) can cause massive slowdowns because WSL uses a network file share to communicate the files between Windows and Linux.

Instead, put your projects somewhere in your Linux home directory (/home/awdeorio). Sub directories are fine.

Bad Example Good Example
/mnt/c/Users/awdeorio/src/eecs485/p1-insta485-static /home/awdeorio/src/eecs485/p1-insta485-static

Root user

Avoid doing everyday coding as the root user in WSL. Some programs don’t work correctly when run as root. When you first installed Ubuntu, you should have been prompted to create a Linux username and password.

Good example: When you start a Bash shell (not a Windows PowerShell), you should have a non-root username.

$ whoami

Bad example: If the default is a root login, here’s how to change your linux username and password. For the same reasons, avoid using su or su root.

# whoami

Next steps

Return to the main set up tutorial.


Original document written by Andrew DeOrio awdeorio@umich.edu.

This document is licensed under a Creative Commons Attribution-NonCommercial 4.0 License. You’re free to copy and share this document, but not to sell it. You may not share source code provided with this document.