p1-insta485-static

Windows Command line tools (WSL)

The Windows Subsystem for Linux (WSL) runs an Ubuntu Linux guest virtual machine on your Windows host machine.

Update Windows

We strongly recommend Windows 11, which supports Linux-based GUI applications. An example is debugging an end-to-end web site test by viewing how the test programmatically clicks links in a browser.

At a minimum, you need Windows 10 build 19044+ or higher. We recommended Windows 11 version 22H2 Build 22621 or higher. Here’s how to check your Windows version.

Free Windows upgrades are available for UM students via OnTheHub.

Install WSL

Follow the EECS 280 WSL Tutorial to install WSL 2.

We require WSL 2. Some software requires WSL 2 to work correctly, for example end-to-end testing of a client-side dynamic pages app using a headless browser. 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 Windows PowerShell. Verify that you are using WSL 2.

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

Update WSL

Even if you have Windows 11 or a high enough version of Windows 10, you still need to update WSL 2 in order to use Linux-based GUI applications.

In Windows PowerShell, run these commands:

$ wsl --update
$ wsl --shutdown

Install CLI tools

You can now use Ubuntu Linux tools, including the apt package manager. Run these commands in an Ubuntu Bash shell:

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

Test a GUI app

To verify that you can successfully run GUI apps on Ubuntu, install x11-apps and run a small GUI app called xeyes.

$ sudo apt install x11-apps
$ xeyes

You should see a new window open with a pair of eyes that follow your cursor.

If it doesn’t work, you may need to update WSL. If you’ve run both wsl --update and wsl --shutdown but it’s still not working, run this:

$ sed -i 's/^export DISPLAY=.*$//g' ~/.bashrc
$ source ~/.bashrc

The first command will remove any lines from your bash config file that start with export DISPLAY=. If you had any such lines, they would have interfered with WSL’s ability to forward GUI apps from Linux to Windows. The second command reloads your bash config file.

Then try running xeyes again. If it still doesn’t open correctly, check if you can upgrade Windows to a newer version.

As a last resort, you can try a fresh install of Ubuntu by running the following commands in Windows PowerShell. This will delete everything in your WSL filesystem!!! Please make sure to back up any important files you have in Ubuntu first. You can copy files on your Linux file system to your normal Windows file system by using the cp command with a Windows directory. (The EECS 280 tutorial shows another option.)

$ wsl --unregister ubuntu
$ wsl --install ubuntu

Finally, make sure to review the WSL Pro-Tips and Pitfalls.

Acknowledgments

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.