As a developer that typically works on Mac or Linux, you will be disappointed with the out-of-the-box terminal in Windows. Lucky for us, Windows supports a fairly smooth Linux integration called the Windows Subsystem for Linux (or WSL for short). If you are unfamiliar with it, Microsoft has a pretty concise explanation:
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 dual-boot setup.
This guide is meant to serve as a quick reference for setting it up yourself (as I recently had to do).
Overview
This guide is not a comprehensive resource for all available options. Instead, I have made some assumptions to help you get it set up quickly.
- You do not want to join the Windows Insider Program and install a preview build of Windows.
- You do want to upgrade to WSL 2.
- You do want to use Ubuntu 20.04 LTS as your Linux distribution.
- You do want to use the Windows Terminal app.
A note about WSL 2 performance
While WSL 2 is more performant than WSL 1 in most cases, there is a specific scenario where it can actually perform worse than WSL 1. This occurs when you are working on files across file systems. Specifically, you will want to make sure you store your project files on the Linux file system instead of the Windows file system (assuming you are using Linux utilities). Microsoft explains this in further detail on Microsoft Docs.
Installation
Let's get started!
Enable WSL 1
We have to first enable WSL 1 before we can upgrade to WSL 2. In PowerShell (as an administrator), run the following command.
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Enable the Virtual Machine Platform feature
To enable the Virtual Machine Platform feature (required for WSL 2), run the following command in PowerShell (as an administrator).
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart your machine
In order to continue the installation of WSL 1 and 2, you will need to restart your machine. This can be done by running the following in PowerShell (as an administrator).
Restart-Computer
Update the Linux kernel
The Linux kernel update package is required to upgrade to WSL 2. To download and run the update, I recommend moving into a different directory since the administrator PowerShell dumps you into the system32 directory. You can accomplish this with the following command in PowerShell (as an administrator).
cd ~ ; wget https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -outfile update.msi ; .\update.msi
You will be prompted to finish the WSL update.
Set WSL 2 as the default
In PowerShell (as an administrator), run the following command to set WSL 2 as the default.
wsl --set-default-version 2
Install Ubuntu 20.04 LTS
Get Ubuntu 20.04 LTS from Microsoft. You will need to click the "Get" link to open the Microsoft Store. From there, you can click "Install" to download and install the Ubuntu distribution.
Launch Ubuntu
The Ubuntu 20.04 LTS app should now be easily searchable in your list of Windows apps. Launch the app to finish setup. You will need to provide a username and password.
Note: If you encounter an error related to virtualization when launching the app, you may need to enable virtualization at the BIOS level.
Install Windows Terminal
Get Windows Terminal from Microsoft. You will need to click the "Get" link to open the Microsoft Store. From there, you can click "Install" to download and install the app. For more information on Windows Terminal, head over to Microsoft Docs.
Set Ubuntu as the default shell
To set Ubuntu as the default terminal in Windows Terminal, you will need to edit the settings.json file. To open this, click the dropdown arrow next to the new tab button and click on "Settings" near the bottom of the menu that pops up. The file will look something like this (unnecessary info has been removed).
{
"defaultProfile": "{a-random-uuid-for-powershell}",
"profiles": {
"list": [
{
"guid": "{a-random-uuid-for-powershell}",
"name": "Windows PowerShell"
},
{
"guid": "{a-random-uuid-for-ubuntu}",
"name": "Ubuntu-20.04"
}
]
}
}
You just need to update the defaultProfile property with the UUID for Ubuntu and save the file.
Use the Linux file system as your default
When you launch Windows Terminal, you will be presented with the Ubuntu shell, but you will be dropped into the Windows file system. As mentioned above, WSL 2 works best when you use the Linux file system. To change your default directory to your Linux user's home directory, you just need to run the following command in the Ubuntu shell (your new default for Windows Terminal).
echo 'cd ~' >> ~/.bashrc
You can change ~ to something else if you would like, but the home directory is usually a safe place to land in.
Closing
While this isn't necessarily a short article, I believe it is pretty concise. It aggregates information from a few sources to hopefully get you up and running with WSL 2 and Windows Terminal as quickly as possible.
Top comments (8)
I already tried it, but can't say it's worth the effort setting up. The performance was abysmal, so I went back to running Linux in a VM. A colleague reported the same experience.
Are there known issues that affect performance that can easily be fixed?
First of all, thanks for taking the time to mention this! To answer your question, there are a number of reasons why performance could be impacted, but my best guess without any context is that you are working on files across the file systems. Here is a resource that explains this issue in more depth.
docs.microsoft.com/en-us/windows/w...
The recommendation is to store files in the Linux file system if you are working in the Linux terminal. I will add this as a disclaimer in the article!
Edit: the article has been updated.
Thanks for the suggestion; though I did already dismiss that particular cause. In the end trying to get WSL working reminded me why I ditched Windows for development work in the first place. I much prefer Linux; so I guess I'll just stick with my VM :)
My current dev environment is docker run under WSL 2. So it's using Linux containers.
Images I use/build are all Linux based (mostly on Alpine). They run much much more efficient than running docker under Windows (Windows containers that have to host Linux based images).
I mainly develop in php (Laravel) with specific image builds for each project (php versions, extensions, os packages, etc) plus support images for services (DBs, cache systems, web servers, etc). In most cases all organized per project in docker-compose dev files.
Also I mainly use VS Code that integrates very nicely with docker "dev" containers, running its server components in the image itself and then communicating with the "client" (UI) running on Windows. So things like linting, git are much more responsive and lean than under Windows containers.
This setup has greatly improved my docker-based workflow. Unit tests (phpunit) run much faster than with docker directly under Windows. Same for DBs and all other supporting images.
It also made much quicker to switch working between different projects. Containers are up in a fraction of the time they were under Windows, and that was already faster than starting VMs prior to switching to Docker.
If your workflow resembles mine I strongly suggest to investigate about proper setting of WSL 2 on your Windows machine.
It's true that there are a few potential hiccups. I had not experienced any major problem, but there are some often reported. If you happen to not encounter them or success in fixing them it might be very worth!
And finally my experience is very good also in regard to Windows Terminal, default profile is the Ubuntu one with start directory my "code" dir ready to CD into the project folder, fire up the containers and log into the dev one... Very quick, clean and efficient
Glad to hear you are enjoying this setup! I am also a fan, and I plan to do a follow-up article for getting Docker setup with WSL 2. That being said, you raised a good point about the default directory for the Linux terminal, so I am going to update the article with instructions for that change! Thanks!
Edit: the article has been updated.
I'm currently running wsl1 , wsl2 broke my network and gave me multiple networking issues , I couldn't install any packages whatsoever, so for now I'll stick with 1
Thanks for replying! This is a known issue, and there are a few options for fixing it. This thread on GitHub has a lot of information about the issue you are running into.
github.com/microsoft/WSL/issues/5336
While it's hard to say which problem you are running into specifically, it seems to be commonly related to DNS. This answer in particular has a largely positive response.
That's awesome , I'll have to upgrade and see if that fixes the issue !