A guide for using WSL for development

8 min readMar 17, 2019

I’ve always been a UNIX fan (and if I’m being honest, a bit of a Windows bigot), but I recognise it’s because my roots are in UNIX. I worked for 17 years as an AIX programmer for IBM.

In the full stack web development bootcamp I teach, a fair number of students come to class with Windows installed on their laptops. Experienced developers know that Windows isn’t the most friendly OS for web development (Ok — it’s downright painful). We thought about requiring that students install Linux or bring in a Mac, but we’ve found that with Windows 10, the support of the Windows Subsystem for Linux (WSL) is sufficient for teaching the course (although I would still encourage anyone who plans to use their laptop for web development to get a Mac or install Linux).

On this journey, I have found some things that make the experience of using WSL better for our students, and I thought I would share those here for people using it for the same purpose.

Getting started

1. Enable the optional feature from an Administrator PowerShell first

Open PowerShell as Administrator (search for PowerShell from the start menu, right click instead of clicking to open, and choose to open as Administrator). Type the following:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

This will prompt you to restart your computer. Let it happen — you should be used to this by now as a Windows user (Ok — I promise that’s my last dig at Windows).

2. Install VS Code (or the IDE of your choice) before you install the WSL

In this article, I’m going to assume you’re using VS Code and will refer to that. When you install the WSL, it will inherit PATH from your Windows environment. Don’t worry too much about what that means, but understand that if you don’t have your IDE installed before you install/initiate the WSL, the executable for your IDE won’t be available to your WSL environment. For this reason, you should make sure that VS Code is installed in Windows before you install the WSL. If it isn’t, you’ll have to add the executable for VS Code to your PATH in WSL in one of your config files (like your .bashrc).

3. Use the latest Ubuntu image offered

Go to the Windows App store and search for Ubuntu. The latest available right now is 18.04. Install the latest.

You’ll have to initialise Ubuntu (from now on, I’ll use the term ‘WSL’ and ‘Ubuntu’ interchangeably).

Once it installs it will prompt you to enter a username and password. This is for your Ubuntu environment and has nothing to do with your Windows username and password. Choose a username without spaces or special characters that is easy to type and remember. Choose a password you will remember (you’ll have to use it often to install tools in your Ubuntu environment).

Setting up your dev environment to use WSL

4. Configure VS Code (or IDE of your choice) to use bash or wsl for interactive terminal

In VS Code, search settings for “integrated.shell”, and replace the line with Powershell with this:

“terminal.integrated.shell.windows”: “C:\\WINDOWS\\System32\\wsl.exe”

If you are using 32-bit VS Code, you will have to reference bash.exe in sysnative instead of wsl:

“terminal.integrated.shell.windows”: “C:\\WINDOWS\\sysnative\\bash.exe”

5. Create a link from your WSL to your C drive

As I mention in subsequent steps below, you should store all of your project files and development work on your C drive, in case you need to reinstall the WSL (Windows has done pretty well with the WSL, but sometimes it just stops working and you have to uninstall and reinstall it). Your WSL has access to your C drive in Windows, but your Windows environment does not have access to your WSL files (well — there are claims that it is possible in the latest versions of the WSL but it’s very hard to set up, and not necessary if you just follow this step to keep your work on your C drive). From the WSL, your C:\\ directory in Windows is called ‘/mnt/c’.

To make it easier to use your C drive from your WSL, use the ‘ln’ command from your home directory on the WSL command line to create a link to your C drive from your Ubuntu home directory. Decide where you want to put your development project files in your C drive. For this example, let’s assume you want to put all of your project files in “C:\\projects\”, and that this directory doesn’t exist yet. Here are the steps you should follow:

a. Open your WSL. If you aren’t there, cd to your home directory. The ‘cd’ command with no arguments will take you to your home directory:

cd

b. Create the “C:\\projects” directory from the WSL:

mkdir /mnt/c/projects

Verify from your Windows File Explorer that this directory was indeed created in Windows.

If you have a problem here — namely that you aren’t allowed to create the directory, you have encountered one of the unusual issues with the WSL. For some users, the windows C mount is owned by root. If this is true for you, you’ll have to create your directory in your windows user’s home directory instead.

You can check for this problem by running

ls -l /mnt

If ‘c’ is owned by ‘root’, create the ‘projects’ directory in /mnt/c/Users/<yourUser> instead.

c. Create the link to “C:\\projects”. Make sure you are still in your home directory in the WSL and type (if you created ‘projects’ in your windows user home directory, use that path instead):

ln -s /mnt/c/projects

d. This will create a projects directory in your WSL home directory. Verify it points to the Windows directory:

ls -l

This should show the projects directory in WSL points to /mnt/c/projects. If the text is red, that indicates a problem. Make sure you verified step b above, and that you ran the command exactly as shown in step c. If it shows red, remove it with ‘rm -rf projects’, and follow steps b and c again.

Test that your link works. Create a file in the linked directory with this command:

touch ~/projects/newfile.txt

Verify from your Windows File Explorer that there is a new text file in the C:\\projects\ directory called ‘newfile’.

6. Keep all of your project files and development work in a linked C drive directory

From now on, do all of your work from the directory link created in number 5 above, or some other linked Windows directory in your WSL environment. If you do that, even if you have to reinstall the WSL, you won’t lose any work!

Get into the habit of opening your WSL, change directory to the linked directory — in our example ‘cd ~/projects’, and then to some subdirectory of that linked directory where you are doing your work, and launch VS code from there with: code .

7. If you use SSH, use the same keys from your Windows and WSL environment

UNIX users like to use ssh, because we don’t like to type in our username and password all the time when we connect to remote servers regularly. For example, I prefer to use ssh to connect to my GitHub repositories. You don’t have to use ssh. If you want to use ssh or are already using it from Windows, you can follow this step. Otherwise, just go past it to step 8.

If you have already generated and are using ssh keys from your Windows environment, you can copy them into your WSL home directory like this:

a. From your WSL, get to your home directory:

cd

b. Copy the keys from your Windows user home directory to your WSL user home directory. In the command below substitute your Windows user name for <your windows user name here>:

cp -r /mnt/c/Users/<your windows user name here>/.ssh ~/.

c. Remove read/write permissions from the private key (this assumes your private key is named id_rsa. If it isn’t, replace it in the command below):

chmod 700 ~/.ssh/id_rsa

This will allow you to use the same keys you are already using to access remote servers from your laptop/computer.

If you don’t have ssh keys in Windows yet, you can generate ssh keys with ssh-keygen in your WSL home directory and copy it to Windows like this:

a. From your WSL, get to your home directory:

cd

b. Generate the keys. After running ssh-keygen just type enter three times to generate the default file names and no passcode:

ssh-keygen<enter><enter><enter>

c. Copy the keys to your Windows home directory. In the command below substitute your Windows user name for <your windows user name here>:

cp -r ~/.ssh /mnt/c/Users/<your windows user name here>/.

That’s it! Now if you have to reinstall your WSL, you can just copy the keys from Windows back over and avoid recopying your public key to remote hosts. If that doesn’t make sense — don’t worry too much about it. Like I said at the start, you don’t have to use ssh. Maybe I’ll write another blog post on using ssh :).

8. Create a script for all of the things you are installing in WSL to support development

As you develop things, you’ll need to install tools and libraries. If you’re developing in JavaScript for example, you’ll likely install NodeJs, NPM, Express, and some front-end framework or environment like AngularJs or React.

a. Create a script file in your mounted Windows drive called wsl_setup.sh:

touch /mnt/c/projects/wsl_setup.sh

b. Give it execute permission:

chmod 755 /mnt/c/projects/wsl_setup.sh

Every time you run a command to install something into your WSL, add the command to the wsl_setup.sh script.

For example, to install NodeJs, you will have to run:

sudo apt install nodejs

That command should be added to your wsl_setup.sh script:

a. Open the wsl_setup.sh script in VS Code:

code /mnt/c/projects/wsl_setup.sh

b. Add the command you ran to install NodeJs to the script in VS Code

If you do this, when you have to reinstall your WSL, you can just run your wsl_setup.sh script to get all of your tools reinstalled.

What’s next?

This is a good start. I’ll stop here to avoid writing a whole book. If you can follow these steps, you’ll have a decent setup for development on Windows with WSL, and it may save you some tears.

Have you had your own experiences using WSL as a developer and best practices? Share them here or on Twitter (I’ll post this under @JanelBrandon12).