Set up Linux Dev Environment On Windows 10 Machine With WSL2, Docker, and Visual Studio Code
Why Use Windows Subsystem for Linux 2 (WSL 2)?
According to Microsoft doc, “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.”
Unlike WSL 1, which uses a translation layer between Linux and Windows, the latest WSL 2 uses virtual machine technology to allow you to run a real Linux kernel directly on Windows 10. WSL 2 also allows you to run Docker natively on Windows 10.
Installation of WSL 2
You need to install WSL 1 and update to WSL 2, and here are the official instructions you’d need to follow. Just be aware to check if your Windows version meets the requirements for WSL 2.
- For x64 systems: Version 1903 or higher, with Build 18362 or higher.
- For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
- Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.
You can select the Start button > Settings > System > About, to check which edition and version of Windows your device is running.
Another detail, in the official doc, Step 5 — Set WSL 2 as your default version, the command in PowerShell is :
wsl --set-default-version 2
I found this doesn’t work for me at first. Since I’ve had Ubuntu 20.04 installed already, I need to upgrade my existing Linux distro to v2 first, so you can add this step between Step 4 and Step 5. You could run this in PowerShell, and wait for a couple of minutes for the upgrade.
wsl --set-version <distro name> 2 // in my case, wsl --set-version Ubuntu-20.04 2
With the above command, you can change back to WSL 1 at any time by replacing the ‘2’ with a ‘1’.
At this point, the WSL 2 should be properly installed on your Windows10 machine. You can verify this with PowerShell or Linux terminal:
wsl -l -v
In my Ubuntu terminal:
wsl.exe -l -v
With WSL 2, you can install programs like node.js, npm, Python, Git…etc. You can view different development paths on Windows 10 here.
I hadn’t realized WSL 2 was available until I upgraded Docker one day, and saw this popped out:
According to Docker's documentation, “Windows Subsystem for Linux (WSL) 2 introduces a significant architectural change as it is a full Linux kernel built by Microsoft, allowing Linux containers to run natively without emulation.”
Installation of Docker
Download Docker Desktop for Windows, and install it.
I remember there are a lot of steps to make Docker work on WSL 1, and here is the article I followed to do the workaround. Luckily, with WSL 2, you shouldn’t need to install or config anything related to Docker under your WSL Linux distro. There are only some settings you need to check with Docker:
From the Docker menu, select Settings->General, select the Use WSL 2 based engine check box. Click Apply & Restart. If you have installed Docker Desktop on a system that supports WSL 2, this option will be enabled by default.
When Docker Desktop restarts, go to Settings > Resources > WSL Integration. Click Apply & Restart. WSL Integration will be enabled on your default WSL distribution. Optionally, select any additional distributions you would like to enable WSL 2 on.
Now, if everything goes fine you should have output like this:
NOTE: When you start running Docker, you might encounter error messages like
Docker can’t connect to docker daemon Here is my preferred answer on Github. You can try to uninstall Docker from Windows and WSL, and install the latest version of Docker. If these steps still can’t fix the issue, you could try uninstalling your Linux distro (Like Ubuntu) and reinstall it.
Visual Studio Code
According to VS code doc, “The Visual Studio Code Remote — WSL extension lets you use the Windows Subsystem for Linux (WSL) as your full-time development environment right from VS Code. You can develop in a Linux-based environment, use Linux-specific toolchains and utilities, and run and debug your Linux-based applications all from the comfort of Windows.”
Installation of Visual Studio Code
Install Visual Studio Code on the Windows side (not in WSL).
Open a remote folder or workspace
FROM THE WSL TERMINAL
Opening a folder inside the Windows Subsystem for Linux in VS Code is very similar to opening up a Windows folder from the command prompt or PowerShell.
- Open a WSL terminal window (using the start menu item or by typing
wslfrom a command prompt / PowerShell).
- Navigate to a folder you’d like to open in VS Code (including, but not limited to, Windows filesystem mounts like
code .in the terminal. When doing this for the first time, you should see VS Code fetching components needed to run in WSL. This should only take a short while, and is only needed once.
- After a moment, a new VS Code window will appear, and you’ll see a notification that VS Code is opening the folder in WSL. VS Code will now continue to configure itself in WSL 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 VS Code as you would normally!
That’s it! Any VS Code operations you perform in this window will be executed in the WSL environment, everything from editing and file operations, to debugging, using terminals, and more.
FROM VS CODE
Alternatively, you can open a Remote WSL window directly from VS Code:
- Start VS Code.
- Press F1, select Remote-WSL: New Window for the default distro or Remote-WSL: New Window using Distro for a specific distro.
- Use the File menu to open your folder.
If you already have a folder open, you can also use the Remote-WSL: Reopen in WSL command. You will be prompted which distro to use.
If you are in a WSL window and want to open the current input in a local window, use Remote-WSL: Reopen in Windows.
Thanks for reading! I hope this article is useful when you try to set up a Linux dev environment with your Windows machine to leverage the best parts of two systems. Happy coding!