Install and configure the Windows Subsystem for Linux 2 (WSL2) on Windows 10

By Philippe Beraud, Microsoft France

This walkthrough covers all the steps required to configure a Windows 10 machine with the WSL2 feature

installed on it.

(Web) developers, DevOps, Systems admins, University students, and many more asked Microsoft over the past

few years for a better command line interface (CLI) experience on Windows. Related expectations notably

comprise a Bash shell that leverages CLI muscle memory (ls, grep, cat, etc.) and runs shell scripts, along with a SSH

client.

As a first answer to such expectations, Microsoft unveiled during the Microsoft Build 2016 the Windows

Subsystem for Linux (WSL) to somehow put Linux on Windows 10. WSL is a feature of Windows 10.

As such, WSL is a genuine Linux Bash shell on Windows. It lets you run a GNU/Linux environment -- including

most command-line tools, utilities, and applications (ssh, sed, grep, awk, tail, ls, vim, htop, etc.) -- directly on

Windows 10, unmodified, without the overhead of a virtual machine (VM).

Moreover, WSL allows you to use your Linux distro(s) of choice directly from your Windows 10 machine. It indeed

provides a multi-distro support (Ubuntu, openSUSE, SLES, Fedora, etc.). The Windows Store provides reliable

downloads for theses distro with the ability to install multiple distros side-by-side.

All the installed distros can run simultaneously. In addition, WSL allows you to invoke Windows exe’s from within

Linux, and conversely invoke Windows apps from within Linux. You can also run background services, daemons.

WSL, with all the above, already represents a more than welcome connected experience for everyone using the

Windows 10 platform for cross-platform development, DevOps, and administration.

Note For more information, see the WSL documentation1, or the WSL learning resources page2.

The next version of WSL, i.e. WSL2, is about to arrive later this year. It has been announced at the

Microsoft Build 2019 conference last year.

Note For more information, see blog posts ANNOUNCING WSL23, and WSL2 POST BUILD FAQ4.

WSL2 is a new version of the architecture in WSL (e.g. WSL 1) that changes how Linux distros interact with

Windows, allowing Linux applications to have full access to their normal system calls and Linux containers to run

natively, all of that without emulation. See Deliver an improved Linux experience on Windows 10 for developers

and beyond.

1 WINDOWS SUBSYSTEM FOR LINUX DOCUMENTATION: https://aka.ms/wsldocs

2 LEARN ABOUT WINDOWS CONSOLE & WINDOWS SUBSYSTEM FOR LINUX (WSL): https://aka.ms/learnwsl

3 ANNOUNCING WSL 2: https://devblogs.microsoft.com/commandline/announcing-wsl-2/ 4 WSL 2 Post BUILD FAQ: https://devblogs.microsoft.com/commandline/wsl-2-post-build-faq/

One should note that WSL2 also contains some experience differences compared to WSL 1. The most important

are the fact that you will need to store you Linux files in your Linux root file system to have increased file system

performance.

Note For more information, see article USER EXPERIENCE CHANGES BETWEEN WSL 1 AND WSL25.

As of this writing, testing WSL2 requires Windows 10 20H1 preview builds as part of the Windows Insiders

program (see below).

Note For more information, see blog post WSL2 IS NOW AVAILABLE IN WINDOWS INSIDERS6.

Let’s see how to:

1. Setup WSL2,

2. Use Visual Studio Code with WSL2,

3. Leverage Docker Desktop WSL 2 backend.

This is the purpose of the next sections.

Setting up Windows Subsystem for Linux (WSL) 2

To get started, if not already present on your local Windows 10 machine, install WSL2 Preview along with the

Ubuntu18.04 distro from the Windows Store and the WSL2 Docker Desktop Tech Preview.

To install WSL2 preview, you will need to fulfill the following requirements:

1. Windows 10 build 18932 or higher. You can check your Windows version by opening a Windows

command prompt and running the ver command. To make sure you are using build 18932 or higher

please join the Windows Insider Program and select the Fast ring.

WSL2 requires Windows 10 build 18917 or higher. However, Docker WSL2 Tech Preview requires Windows

10 build 18932 or higher. See below

Important note The above means that you should only use these bits for NOT production environments.

2. A machine that supports the Hyper-V virtualization technology.

If so, perform the following steps:

Note For more information, see article INSTALLATION INSTRUCTIONS FOR WSL27.

1. Install WSL 1. Open a PowerShell command prompt as an Administrator and run the following command:

PS C:\> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

5 USER EXPERIENCE CHANGES BETWEEN WSL 1 AND WSL 2: https://docs.microsoft.com/en-us/windows/wsl/wsl2-ux-changes

6 WSL 2 IS NOW AVAILABLE IN WINDOWS INSIDERS: https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/

7 INSTALLATION INSTRUCTIONS FOR WSL 2: https://docs.microsoft.com/en-us/windows/wsl/wsl2-install

Restart your computer when prompted. Press Y to do so when invited.

Note For specific instructions, see article WINDOWS SUBSYSTEM FOR LINUX INSTALLATION GUIDE FOR WINDOWS 108.

2. Install a default distribution based on Ubuntu 18.04 from the Microsoft Store9.

Once installation is complete, you will be prompted to create a new user account (and its password).

3. The Ubuntu distro as most distros ship with an empty/minimal package catalog. It’s strongly

recommended to regularly update your package catalog, and upgrade your installed packages using your

distro's preferred package manager. Run the following commands from the Bash prompt:

$ sudo apt update && sudo apt upgrade

8 WINDOWS SUBSYSTEM FOR LINUX INSTALLATION GUIDE FOR WINDOWS 10: https://docs.microsoft.com/en-us/windows/wsl/install-win10

9 Ubuntu 18.04: https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q

4. Once completed, now enable the 'Virtual Machine Platform' optional component. Open a PowerShell

command prompt as an Administrator and run the following command:

PS C:\> Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

After these changes are enabled you will need to restart your computer. Press Y to do so when you will be

asked for a confirmation.

5. Run the following command to retrieve the name of your current distro. Copy this actual name of your

distro: Ubuntu-18.04.

PS C:\> wsl -l -v

6. Set your current distro as the one to be backed by WSL2 using the following command in PowerShell:

PS C:\> wsl --set-version Ubuntu-18.04 2

You can change back to WSL 1 at any time by running the same command as above but replacing the '2'

with a '1'.

Depending on your environment, you may end up with the following error after a couple of seconds:

To resolve this error, open a Windows command prompt with administrative privileges and run the

following two commands:

C:\> fsutil behavior set disableencryption 1 C:\> fsutil behavior set disablecompression 1

When creating the VHD's, those will ensure that compression and encryption are both disabled on them.

Restart your machine.

Note For more information, see article FSUTIL BEHAVIOR10.

If this workaround doesn’t solve the issue, go to the Ubuntu directory in your profile folder, i.e. something

like %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited..., right-click on LocalState, and

select Properties.

10 FSUTIL BEHAVIOR: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/fsutil-behavior

Click on Advanced and uncheck Compress contents to save space and Encrypt contents as well if

that's checked. Click on OK twice. When a dialog asks whether you want to apply to just this folder or to

all subfolders and files, you can say "just this folder", because all you're doing is clearing that "compress"

flag. Restart your machine. After that, the wsl --set-version command should work.

Note For more information, see issue WSL2: VIRTUAL HARD DISK FILES MUST BE UNCOMPRESSED AND UNENCRYPTED AND MUST

NOT BE SPARSE #410311 on GitHub.

7. Set Ubuntu 18.04 as the default distribution:

PS C:\> wsl -s Ubuntu-18.04

Additionally, if you want to make WSL2 your default architecture you can do so with this command:

PS C:\> wsl --set-default-version 2

This will make any new distro that you install be initialized as a WSL2 distro.

8. Verify what versions of WSL your distros are using:

PS C:\> wsl --list --verbose

11 WSL2: VIRTUAL HARD DISK FILES MUST BE UNCOMPRESSED AND UNENCRYPTED AND MUST NOT BE SPARSE #4103:

https://github.com/microsoft/WSL/issues/4103

The distro that you've chosen above should now display a '2' under the 'version' column.

Important note As outlined in blog post WSL2 IS NOW AVAILABLE IN WINDOWS INSIDERS12, “make sure to put the files that

you will be accessing frequently with Linux applications inside of your Linux root file system to enjoy the file performance

benefits. To enjoy the faster file system access in WSL2 these files must be inside of the Linux root file system.”

Note It’s possible for Windows applications to access the Linux root file system like File Explorer! Try running

explorer.exe / in the home directory of your Linux distro and see what happens.

Let’s now see how to use Visual Studio Code in conjunction.

Using Visual Studio Code with WSL2

Visual Studio Code is a powerful, lightweight code editor redefined and optimized for building and debugging

modern web and cloud applications. Visual Studio Code supports almost every major programming language.

Common web-based languages like JavaScript, TypeScript, CSS, and HTML ship in the box, and rich extensions

from the Visual Studio marketplace provide completions, linting, debugging, and refactoring support for hundreds

more.

It benefits from the IntelliSense technology, i.e. smart code completions based on variable types, function

definitions, and imported modules. It allows you to easily navigate large code bases with features like Go To

Definition and Find All References, to debug code right in the editor using breakpoints, a full call stack, and an

interactive console, etc.

Visual Studio Code is free and Open Source.

To install Visual Studio Code and connect it with WSL2, perform the following steps:

1. Install Visual Studio Code or Visual Studio Code – Insiders13.

2. Launch Visual Studio Code.

12 WSL 2 IS NOW AVAILABLE IN WINDOWS INSIDERS: https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/

13 Visual Studio Code – Insiders: https://code.visualstudio.com/insiders

3. Install the Remote Development extension pack14. This pack notably includes the Visual Studio Code

Remote - WSL15 extension that allows you to get a Linux-powered development experience from the

comfort of Windows 10 by opening any folder in WSL2.

Note For details on setting up and working with the WSL extension, see article DEVELOPING IN WSL1617. For

troubleshooting tips and tricks, see article REMOTE DEVELOPMENT TIPS AND TRICKS18.

4. To connect Visual Studio Code to WSL2, open a WSL2 terminal window and launch Visual Studio Code

from here:

a. Open a WSL2 terminal window using the Start Menu item or by typing “wsl” from the command

prompt.

b. Navigate to a folder you'd like to open in Visual Studio Code (including, but not limited to,

Windows filesystem mounts like the folder /mnt/c for the C drive on your Windows 10 local

machine.

c. Type in the terminal the following command:

$ code .

When doing this for the first time, you should see Visual Studio Code fetching components

needed to run in WSL2. This should only take short while and is only needed once.

Note If this command does not work, you may not have added VS Code to your path when it was installed.

14 Remote Development Extension Pack: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-

extensionpack 15 Visual Studio Code Remote – WSL: https://aka.ms/vscode-remote/download/wsl

16 DEVELOPING IN WSL: https://code.visualstudio.com/docs/remote/wsl

17 DEVELOPING INSIDE A CONTAINER: https://code.visualstudio.com/docs/remote/containers 18 REMOTE DEVELOPMENT TIPS AND TRICKS: https://code.visualstudio.com/docs/remote/troubleshooting#_installing-a-supported-ssh-client

d. After a moment, a new Visual Studio Code window will open up, and you'll see a notification that

Visual Studio Code is starting in WSL2.

Visual Studio Code will now continue to configure itself in WSL2 and keep you up to date as it makes progress.

Once finished, you now see a WSL indicator in the bottom left corner, and you'll be able to use Visual Studio Code

as you would normally!

ET voila! Any Visual Studio Code operations you perform in this window will be executed in the WSL2

environment, everything from editing and file operations, to debugging, using terminals, and more.

Note For more information, see blog post WSL2 WITH VISUAL STUDIO CODE19.

Let’s now consider how to deploy Linux containers with Docker Desktop.

Leveraging Docker Desktop WSL 2 backend

Docker Desktop is an application notably available for Windows 10 machines that allows you to build production-

ready container applications. It integrates with WSL2 in order to seamlessly build and test Linux applications and

easily share them with others, bundling the code and configuration in a lightweight, portable Docker container

application that runs the same everywhere else.

With the Docker Desktop WSL 2 backend, you will get access to Linux workspaces, removing the need to maintain

both Linux and Windows build scripts. WSL2 also supports dynamic memory and CPU allocation and an improved

startup time down from 40 seconds to 2 seconds!

19 WSL 2 WITH VISUAL STUDIO CODE: https://code.visualstudio.com/blogs/2019/09/03/wsl2

Note For more information, see articles Introducing the Docker Desktop WSL 2 Backend20, DOCKER DESKTOP WSL

TECH PREVIEW21 and blog post DOCKER ❤️ WSL2 – THE FUTURE OF DOCKER DESKTOP FOR WINDOWS22. Also watch the episode Docker

Desktop Integration with WSL23 on Channel 9.

Installing Docker Desktop WSL 2 backend

Perform the following steps:

1. Download the Docker Desktop Edge 2.1.6.024 or later.

2. Ensure you have completed all the steps described BEFORE installing the WSL2 Docker Desktop

WSL 2 backend.

3. Launch the installer and follow the usual Docker Desktop Edge installation instructions to install the

Docker Desktop WSL 2 backend.

After a successful installation, you may be invited to install an update that vehicles the Docker Desktop

WSL 2 backend.

If so, click on Install Update.

Configuring the WSL 2 integration

See Docker Desktop WSL 2 backend.

Perform the following steps:

1. Open the Docker Desktop menu.

2. Select Settings > General from the Docker menu.

3. Select Enable the experimental WSL2 based engine and click Apply & Restart.

20 INTRODUCING THE DOCKER DESKTOP WSL 2 BACKEND: https://www.docker.com/blog/new-docker-desktop-wsl2-backend/ 21 DOCKER WSL 2 – THE FUTURE OF DOCKER DESKTOP FOR WINDOWS: https://engineering.docker.com/2019/06/docker-hearts-wsl-2/

22 GET READY FOR THE TECH PREVIEW OF DOCKER DESKTOP FOR WSL 2: https://blog.docker.com/2019/07/docker-wsl2-tech-preview/ 23 Docker Desktop Integration with WSL: https://channel9.msdn.com/Shows/On-NET/Docker-Desktop-Integration-with-WSL 24 Docker Desktop Edge preview release: https://download.docker.com/win/edge/40807/Docker%20Desktop%20Installer.exe

4. When Docker Desktop Edge restarts, from the Docker menu, select Settings > Resources > WSL

Integration and then select from which WSL 2 distro you would like to access Docker. For example,

Ubuntu-18.04 in our illustration.

5. Click Apply & Restart for the changes to take effect.

6. Once Docker Desktop Edge restarts, and when the WSL2 daemon starts, a docker CLI context is

automatically created for it, and the CLI configuration points to the context.

You can list contexts by running the following command from a Windows command prompt:

PS C:\> docker context ls

Docker Desktop allows you to toggle between the WSL modes. To use the classic daemon, run the

command

PS C:\> docker context use default

To switch to WSL2, run:

C:\> docker context use wsl Current context is now "wsl"

Configuring a Kubernetes cluster

See Deploy on Kubernetes.

Kubernetes is not activated by default.

Perform the following steps:

1. From the Docker menu, select Settings > Kubernetes and then select Enable Kubernetes.

2. Click Apply & Restart for the changes to take effect.

Kubernetes has been installed and it's now up and running.

1. Open a Bash terminal console on the configured Linux distro on WSL2. For example, Ubuntu-18.04:

C:\> wsl -d Ubuntu-18.04

5. Check whether Kubernetes is running from WSL2:

$ kubectl config use-context docker-desktop Switched to context "docker-desktop". $ kubectl cluster-info Kubernetes master is running at https://kubernetes.docker.internal:6443 KubeDNS is running at https://kubernetes.docker.internal:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Kubernetes is meant for deploying apps and services. So, at this stage, you can further test your cluster.

Creating a test deployment on the cluster

To install a first app, perform the following steps:

1. From the VM Shell, deploy NGINX with 3 replicas (instances) available:

$ kubectl run nginx --image nginx:alpine --replicas 3 kubectl run --generator=deployment/apps.v1 is DEPRECATED and will be removed in a future version. Use kubectl run --generator=run-pod/v1 or kubectl create instead. deployment.apps/nginx created

2. It may take a minute or two to install, but you can check the status. Once NGINX has been deployed,

expose the application:

$ kubectl expose deployment nginx --port 80 --target-port 80 --type ClusterIP --selector=run=nginx --name nginx service/nginx exposed

3. See the new Service and ClusterIP address assigned:

$ kubectl get svc kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 6h34m nginx ClusterIP 10.106.242.120 <none> 80/TCP 10s

4. From the Docker menu, select Dashboard:

5. Hopefully, all of that is working. So, let’s remove the service and pod you have deployed:

$ kubectl delete service nginx service "nginx" deleted $ kubectl delete deployment nginx deployment.apps "nginx" deleted

This concludes this article. Feel free to start using your distro(s) of choice on WSL2 the way you expect on

your Windows 10 machine to build and debug your applications, and deploy your containers!

Optionally, check out the Windows Terminal for the best possible terminal experience on Windows.

Windows Terminal is a new, modern, fast, efficient, powerful, and productive terminal application for users of

command-line tools and shells like Command Prompt, PowerShell, and of course WSL!

Note For more information, see blog post INTRODUCING WINDOWS TERMINAL25.

Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)

25 INTRODUCING WINDOWS TERMINAL: https://devblogs.microsoft.com/commandline/introducing-windows-terminal/