The Windows Subsystem for Linux Guide!¶

Greetings, Earthling! Welcome to The Hitchhiker’s Guide to the Windows Subsystem for Linux (WSL).

This is a living, breathing guide. If you’d like to contribute, fork us on GitHub!

This guide is also available in Chinese.

This handcrafted guide exists to provide both novice and expert Windows and Linux developers a best practice handbook to the installation, configuration, and usage of WSL (Bash on Ubuntu on Windows) on a daily basis.

Background on WSL (Windows Subsystem for Linux)¶

What is WSL?¶

WSL is a full Ubuntu operating system that you can install on your Windows 10 machine.

It’s Beta Software¶

Please keep in mind that this is beta software. This means that any part of it is subject to change, as feedback is collected and improvements are made based on community feedback.

In fact, if you have any issues you run into you, you can open a GitHub issue with Microsoft to let them know about it!

Microsoft’s Creator’s Update includes some improvements to the WSL that are not included in the regular release of Windows yet. The biggest one being that you can launch Windows programs from WSL.

Installing WSL (Bash on Ubuntu on Windows)¶

This document provides step-by-step instructions for installing WSL on your Windows machine.

Step 1: Enable Developer Mode¶

The first thing you need to do is enable developer mode on your Windows machine.

Go to Settings -> Update and Security -> For developers, and click “Developer mode”.

Step 2: Install WSL¶

Next, you need to install WSL.

Go to the Start Menu and search for “turn windows features on or off”. Select that, then check the “Windows Subsystem for Linux (Beta)” checkbox.

Hit OK. Restart your computer.

Step 3: Create a Unix Account¶

Next, we need to activate WSL from the command-line. Open up a Command Prompt and run the following command:

> bash

This will setup your Linux environment on Windows! If you see a blank screen at any point during this process, hit enter, and you’ll be prompted to create a new username for your Linux account.

Step 4: Enjoy!¶

Updating WSL¶

Updating Packages in WSL¶

Because WSL uses a standard Ubuntu installation, upgrading your packages should look very familiar:

$ sudo apt-get update
$ sudo apt-get upgrade

Updating the Ubuntu OS¶

You can aso upgrade to the latest version of Ubuntu with the following command (caution, this will take quite some time)!:

$ sudo -S apt-mark hold procps strace sudo
$ sudo -S env RELEASE_UPGRADER_NO_SCREEN=1 do-release-upgrade

And, it works, just as expected!

Common Gotchas¶

VIM Arrow Keys Don’t Work¶

You may notice that by default, VIM’s arrow keys don’t work on your computer. To fix this, add the following to your ~/.vimrc:

$ cat ~/.vimrc
set term=builtin_ansi

Sudo ‘Unable to Resolve Host’ Warning¶

You may notice that every time you run sudo something, your system complains that it cannot resolve it’s own hostname, but then continues on anyway. To fix this annoyance, you need to add your system’s hostname to /etc/hosts:

$ cat /etc/hosts
127.0.0.1 localhost
127.0.0.1 nova
...

Here, my machine is called ‘nova’.

Connecting to the Linux subsystem via SSH¶

In order to be able to ssh into your Linux subsystem instance follow the steps outlined by Master Azazel in this thread:

sudo apt-get remove openssh-server
sudo apt-get install openssh-server
sudo nano /etc/ssh/sshd_config and disallow root login by setting PermitRootLogin no
Then add a line beneath it that says: AllowUsers yourusername and make sure PasswordAuthentication is set to yes if you want to login using a password.
Disable privilege separation by adding/modifying : UsePrivilegeSeparation no
sudo service ssh --full-restart
Connect to your Linux subsystem from Windows using a ssh client like PuTTY.

GUI Applications¶

Step 1: Installing an X Server¶

In order to run GUI applications in WSL, you need to first install an X Server on your Windows machine. I recommend installing Xming.

Step 2: Set DISPLAY Environment Variable¶

Next, you have to tell your WSL environment to use the X Server by setting the DISPLAY environment variable.

I added the following to my ~/.bashrc:

export DISPLAY=:0