Configure a Linux Development Environment on Windows with WSL and VS Code

By on 18 May 2022

About WSL

It seems like everyone is using Linux or Mac for software development these days, but if you’re a windows user, you may have looked into what you needed to do to be able to use Linux on your PC and found that dual-booting or virtual machines sounded like too much trouble. But these days, most employers want their devs to know their way around the Linux command line. There’s never been a better time for Windows users to start learning those skills since there’s finally a way to have our cake and eat it too. It’s called Windows Subsystem for Linux (WSL).

The Windows Subsystem for Linux lets developers run a GNU/Linux environment — including most command-line tools, utilities, and applications — directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.”

What is Windows Subsystem for Linux | Microsoft Docs

If this sounds interesting, read on as I walk you through setting up a Python development environment in WSL.

Enable and install WSL

In order to use WSL, you must be using Windows version 10 (build 19041 or higher) or any version of Windows 11. For this tutorial I’m using Windows 11 and am also going to integrate Visual Studio Code with WSL so you’ll want to install this too. (WSL is not just for VS Code users, but at the time of this writing, it is the only lightweight code editor that integrates WSL natively.)

To get started on Windows 11, open a Powershell prompt as administrator and run
wsl --install

Note: if you’re using Windows 10 you’ll need to specify the distribution you want to install, e.g.: wsl --install -d Ubuntu

Powershell window showing the process for installing WSL
The process for installing WSL through PowerShell

When prompted, reboot your computer

You should get a PowerShell window prompting you for your credentials to use within the Ubuntu distribution. After entering your new username and password, you should arrive at a Bash prompt.

You can use this shell the same as you would in the Linux terminal and can open it in the future by going to the Start Menu and searching for the Ubuntu app.

Launch your Windows Explorer by pressing WIN + E and you’ll see that you have a new Linux icon at the bottom of your navigation pane. This is a mounted drive that contains all your Linux files.

Access your files through the Linux drive mounted in Windows Explorer
Access your files through the Linux drive mounted in Windows Explorer

Congratulations, you have installed Linux on Windows!

Install Python, Pip, and Venv on Ubuntu

The included Ubuntu distribution already has python installed. Run python3 –version to ensure the version. As of the time of this writing, Python 3.8.2 is included.

Let’s ensure your python is up to date in Linux and you have the basics by returning to the Bash shell (Start Menu -> Ubuntu) and following the next 3 steps

  • If you need to update your version of Python, first update your Ubuntu version by entering: 
    sudo apt update && sudo apt upgrade
    then update Python using sudo apt upgrade python3.
  • Install pip by entering: sudo apt install python3-pip.
  • If you use a virtual environment, install it by entering: sudo apt install python3-venv.

Run VS Code on WSL

Now that you have Linux installed on Windows and have your basic Python installation ready to go, we can start setting up a real Linux development environment in VS Code

Open VS Code and install the extension called Remote WSL

The Remote WSL Extension
The Remote WSL Extension

You will notice a new icon in the lower-left corner of the application. Click that icon to open a remote window.

The new Remote Window icon in VS Code from the Remote WSL Extension
The new Remote Window icon in VS Code from the Remote WSL Extension

From here you have multiple options:

New WSL Window will give you a clean session of VS Code in Linux. Alternatively, you can launch a new session in a different distro (see Windows Store for more distros to download if you wish).

Open Folder in WSL will open any folder on your Windows or Linux drives in VS Code on WSL. Although you can open files in WSL from the Windows file system, I recommend you work with projects and files actually stored within your Linux file system for compatibility. However, if you have a rather large project, porting it over could potentially be a lot of work, and guidance on that process is beyond the scope of this article, always make sure you have your code backed up in case something goes wrong.

The final option is Reopen Folder in WSL which will reload a folder opened in VS Code under Windows and open it under WSL instead.

The Remote Window options
The Remote Window options

For the purposes of this tutorial, click on New WSL Window. A new instance of VS Code will open and it will load into Ubuntu. You know you are running your VS Code instance in Linux by the icon in the lower left.

WSL indicator/button
WSL indicator/button

NOTE: There’s a possibility you may have to adjust some of your settings or reinstall/reconfigure some of your extensions through WSL.

Now that you have the hard part done, there’s just one more thing to walk through.

Creating and running a sample project

You’re all set up and ready to rock with your new Linux environment, but before you go, let’s run a simple hello world.

Create a new python file, write a hello world statement, then File -> Save. Notice VS Code is prompting you to save a file in the Linux file system.

Save prompt with path to Linux home folder
Save prompt with path to Linux home folder

After saving the file, press CTRL + ` to open the integrated terminal. VS Code now opens the default Ubuntu shell (aka “Bash”). If you have never used Linux before, you’ll want to learn the terminal as it’s one of the main benefits you’re getting by going through this process!

Type in the following command and press Enter to see your first program running in Linux on Windows

Hello World running in the terminal
Hello World

Enjoy your new development environment! To learn more about Linux, see Linux.org

Want a career as a Python Developer but not sure where to start?