Best practices for setting up a WSL development environment

A step-by-step guide to help you set up a WSL development environment using Ubuntu, Visual Studio Code, Git, Windows Credential Manager, and with recommended tutorials for everything you might want.

Install WSL

Windows Subsystem for Linux comes with the Windows operating system, but you must enable it and install a Linux distribution before you can begin using it.

To use the simplified --install command, you must be running a recent build of Windows (Build 20262+). To check your version and build number, select Windows logo key + R, type winver, select OK. You can update using the Settings menu or Windows Update Assistant.

If you prefer to install a Linux distribution other than Ubuntu, or would prefer to complete these steps manually, see the WSL installation page for more details.

Open PowerShell (or Windows Command Prompt) and enter:

wsl --install

The --install command performs the following actions:

  • Enables the optional WSL and Virtual Machine Platform components
  • Downloads and installs the latest Linux kernel
  • Sets WSL 2 as the default
  • Downloads and installs the Ubuntu Linux distribution (reboot may be required)

You will need to restart your machine during this installation process.

PowerShell command line running wsl --install

Check the troubleshooting installation section if you run into any issues.

Set up your Linux user info

Once the process of installing your Linux distribution with WSL is complete, open the distribution (Ubuntu by default) using the Start menu. You will be asked to create a User Name and Password for your Linux distribution.

Ubuntu command line enter UNIX username

You may also want to update and upgrade your packages. For Ubuntu, use the command: sudo apt update && sudo apt upgrade.

To add additional Linux distributions, you can install via the Microsoft Store, via the --import command, or by sideloading your own custom distribution. You may also want to set up custom WSL images for distribution across your enterprise company.

Set up Windows Terminal

Windows Terminal can run any application with a command line interface. Its main features include multiple tabs, panes, Unicode and UTF-8 character support, a GPU accelerated text rendering engine, and the ability to create your own themes and customize text, colors, backgrounds, and shortcuts.

Whenever a new WSL Linux distribution is installed, a new instance will be created for it inside the Windows Terminal that can be customized to your preferences.

We recommend using WSL with Windows Terminal, especially if you plan to work with multiple command lines. See the Windows Terminal docs for help with setting it up and customizing your preferences, including:

Windows Terminal screenshot

File storage

  • To open your WSL project in Windows File Explorer, enter: explorer.exe .
    Be sure to add the period at the end of the command to open the current directory.

  • Store your project files on the same operating system as the tools you plan to use.
    For the fastest performance speed, store your files in the WSL file system if you are working on them with Linux tools in a Linux command line (Ubuntu, OpenSUSE, etc). If you're working in a Windows command line (PowerShell, Command Prompt) with Windows tools, store your files in the Windows file system. Files can be accessed across the operating systems, but it may significantly slow down performance.

For example, when storing your WSL project files:

  • Use the Linux file system root directory: \\wsl$\<DistroName>\home\<UserName>\Project
  • Not the Windows file system root directory: C:\Users\<UserName>\Project or /mnt/c/Users/<UserName>/Project$

Windows File Explorer displaying Linux storage

Set up VS Code for editing and debugging

Follow this step-by-step guide to Get started using Visual Studio Code with WSL, which includes installing the Remote Development extension pack. This extension enables you to run WSL, SSH, or a remote container for editing and debugging with the full set of Visual Studio Code features. Quickly swap between different, separate development environments and make updates without worrying about impacting your local machine.

Once VS Code is installed and set up, you can open your WSL project with a VS Code remote server by entering: code .

Be sure to add the period at the end of the command to open the current directory.

VS Code with WSL extensions displayed

Set up version management with Git

Follow this step-by-step guide to Get started using Git on WSL and connect your project to the Git version control system, along with using the credential manager for authentication, using Git Ignore files, understanding Git line endings, and using the Git commands built-in to VS Code.

Displaying git version in the command line

Set up remote development containers with Docker

Follow this step-by-step guide to Get started with Docker remote containers on WSL 2 and connect your project to a remote development container with Docker Desktop for Windows.

Docker Desktop screenshot

Set up a database

Follow this step-by-step guide to Get started with databases on WSL and connect your project to a database in the WSL environment. Get started with MySQL, PostgreSQL, MongoDB, Redis, Microsoft SQL Server, or SQLite.

Running MongoDB in Ubuntu via WSL

Set up GPU acceleration for faster performance

Follow this step-by-step guide to set up GPU accelerated machine learning training in WSL and leverage your computer's GPU (graphics processing unit) to accelerate performance heavy workloads.

Running GPU acceleration with WSL

Basic WSL commands

The Linux distributions that you install via WSL are best managed using PowerShell or Windows Command Prompt (CMD). A few of the basic commands include:

In addition, many commands are interoperable between Windows and Linux. Here are a couple of examples:

  • Run Linux tools from a Windows command line: Open PowerShell and display the directory contents of C:\temp> using the Linux ls -la command by entering: wsl ls -la

  • Mix Linux and Windows commands: In this example, the Linux command ls -la is used to list files in the directory, then the PowerShell command findstr is used to filter the results for words containing "git": wsl ls -la | findstr "git". This could also be done mixing the Windows dir command with the Linux grep command: dir | wsl grep git.

  • Run a Windows tool directly from the WSL command line: <tool-name>.exe For example, to open your .bashrc file (the shell script that runs whenever your Linux command line is started), enter: notepad.exe .bashrc

  • Run the Windows ipconfig.exe tool with the Linux Grep tool: ipconfig.exe | grep IPv4 | cut -d: -f2 This example demonstrates the ipconfig tool on the Windows file system being used to display the current TCP/IP network configuration values and then being filtered to only the IPv4 result with grep, a Linux tool.

Mount an external drive or USB

Follow this step-by-step guide to Get started mounting a Linux disk in WSL 2.

wsl mount command screenshot

Additional resources