Scott Hanselman

How to set up Docker within Windows System for Linux (WSL2) on Windows 10

February 21, 2020 Comment on this post [13] Posted in Docker | Linux | Win10
Sponsored By

MagicI've written about WSL2 and it's glorious wonders many times. As its release (presumably) grows closer - as of this writing it's on Windows Insiders Slow and Fast - I wanted to update a few posts. I've blogged about a few cool thing around WSL and Docker

Here's a little HanselFAQ and some resources.

I want to run Linux on Windows

You can certainly use HyperV or VirtualBox and run a standard Virtual Machine. Download an ISO and mount it and run "a square within a square." It won't be seamlessly integrated within Windows - it'll be like the movie Inception - but it's time-tested.

Better yet, install WSL or WSL2. It'll take 5-10 minutes tops if your Windows 10 is somewhat up to date.

  • How to install WSL on Windows 10
    • WSL doesn't include a Linux kernel. Its Linux file system access is kinda slow, but it accesses Windows files super fast. If you use Cygwin, you'll love this, because it's really Linux, just the kernel is emulated.
  • How to install WSL2 on Windows 10
    • WSL2 ships an actual Linux kernel and its Linux file system is 5x-10x faster than WSL. WSL2 uses a tiny utility VM that expands contracts its memory and you can manage distros with the wsl command line.
    • Do all your development work inside here, while still using VS Code on Windows. It's amazing. Watch me set up a friend with WSL2, LIVE on YouTube.

I want to SSH into Linux stuff from Windows

There's 15 years of websites telling you to install Putty but you might not need it. OpenSSH has been shipping in Windows 10 for over two years. You can add them with Windows Features, or if you like, grab a release and put it on your PATH.

You can also do things like set up keys to use Windows 10's built-in OpenSSH to automatically SSH into a remote Linux machine. I also like to setup Signed Git Commits with a YubiKey NEO and GPG and Keybase on Windows.

I need a better Terminal in Windows

The new Windows Terminal is for you. Download Windows Terminal now for free. It's open source. You can then run the Win64/Win32 ssh from above, or run any Linux distros SSH. Have fun. It's time.

NOTE: Have you already downloaded the Terminal, maybe a while back? Enough has changed that you should delete your profiles.json and start over.

You can download the Windows Terminal from the Microsoft Store or from the GitHub releases page. There's also an unofficial Chocolatey release. I recommend the Store version if possible.

My prompt and fonts are ugly

Make them pretty. You deserve the best. Go get Cascadia Code's CascadiaPL.ttf and PowerLine and buckle up buttercup. Get a nice theme and maybe a GIF background.


I want to use Docker on Windows and I want it to not suck

Surprise, it's actually awesome. You may have had some challenges with Docker a few years ago on Windows and gave up, but come back. There's been a huge (and fascinating) architecture of Docker on Windows. It's very nicely integrated if you have WSL2.

If you have WSL2 set up nicely, then get Docker Desktop WSL2. This version of Docker for Windows uses WSL2 as its engine allowing you to share your docker context across Windows and Linux on the same machine! As the maker intended!

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. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid having to maintain both Linux and Windows build scripts.

So that means

  1. Install Windows 10 Insider Preview build 19018 or higher
  2. Enable WSL 2 feature on Windows. For detailed instructions, refer to the Microsoft documentation.
  3. Download Docker Desktop Edge or a later release.

Ensure your default WSL instances is WSL2. You can do that with wsl -l -v, and then wsl --set-version  <distro> 2

Then within Docker Desktop for Windows you've got two things to check. First, are you using WSL2 as your backend?

Docker for Windows | Enable WSL2

And then, the often missed setup, check under Resources | WSL Integration and tell Docker which WSL2 distros you want to use to access Docker. If you're paying attention you may notice that Docker Desktop tries to prompt you with a notification in Action Center but you might miss it.

Docker | Resources | WSL Integration

NOTE: If you used an early Tech Preview, you might have an extra now-vestigial Docker context named "wsl." You want to use the Default one, not the WSL one.

This isn't intuitive or obvious and you might get weird errors like these

docker wsl open //./pipe/docker_wsl: The system cannot find the file specified.


error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.

You can see if you have an extra context from before like below. That "wsl" one is older (if you have it) and you want to use default in both Windows and WSL2.

docker context ls
default * Current DOCKER_HOST based configuration npipe:////./pipe/docker_engine https://kubernetes.docker
wsl Docker daemon hosted in WSL 2 npipe:////./pipe/docker_wsl

I actually removed that one to avoid confusion with docker context rm wsl.

Here's Ubuntu on my Windows machine

Docker in Ubuntu

And here's my Windows machine. Note that docker images in both instances returns the same list. They are the same Docker backend!

Docker on Windows

I want to code in VS Code on Windows but compile on Linux

At this point once I've set things up I can go bananas. I can do Container-based development, where I use VS Code to run all my developer tools and builds insider a container...maybe I never event install Go or PHP or .NET Core. It's all just inside a container.

Oh, by the way, please Subscribe to my YouTube! I talk a lot about this stuff over there.

Sponsor: Couchbase gives developers the power of SQL with the flexibility of JSON. Start using it today for free with technologies including Kubernetes, Java, .NET, JavaScript, Go, and Python.

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Hosting By
Hosted in an Azure App Service
February 27, 2020 7:02
I think there's a typo: "This ships an actual Linux kernel and its Linux file system is 5x-10x faster than WSL2. Do all your development work inside here, while still using VS Code on Windows. It's amazing. Watch me set up a friend with WSL2, LIVE on YouTube." It should be WSL instead of "WSL2"?
February 27, 2020 7:18
Thanks Philip!
February 27, 2020 10:15
Hi Scott, thanks for all the amazing work you put in this posts! I recall that accessing /mnt/c/ filesystem from WSL2 was very slow (painful for git operations) - is that issue already resolved? I want to store my code in Windows filesystem (for quick IDE updates), but do all my command line related work (git, console commands) from linux and I'd love to have my fancy git prompt working quickly.
February 27, 2020 13:26
WSL2 is great, but insider builds are a pain, too much updates all the time. And in the end, I just dual-boot Ubuntu and do development there, Windows is for games and photo/video. Most dev-related things are just faster on Ubuntu. Git is A LOT faster when you have large repos.
February 27, 2020 13:30
I thought that setting it up will take much more work, but it isn't that much. Very good tutorial. Thanks
February 27, 2020 15:33
I've been using WSL2 with the Windows Insider Slow enabled. It's been great and a pretty seamless experience. I've tried installing Linux desktop directly but the software is so buggy that I spend all my time just trying to get the thing to work - not to mention that it is missing features like a text to voice for reading articles (I'm a slow reader :-) ). So, using Windows with WSL2 is a great middle ground. You get the great software that is Windows with the great development that is Linux - or rather those that only like supporting Unix systems as a first class citizen it removes those barriers. The only trouble I had was setting up the NeoVim copy paste, which wasn't too bad getting to work. And occasionally Windows will lose the connection with WSL2 when using localhost. But you just need to run a PowerShell command to reset things and everything is dandy again.
February 27, 2020 20:27
Docker is nice. Apps running in containers cannot impact the underlying OS. I wish there was a version of Docker for Windows too so that we could run Windows apps inside containers and not worry about them overwriting DLLs or filing every obscure nook and cranny of the file system with their own files.
February 27, 2020 21:30
Fleet Command: You can use Windows Containers with Docker:
February 28, 2020 2:45
@David: "Windows Containers" aren't what you think. That beautiful name fooled me for two monthes while I was trying to figure out how to containerize a copy of Final Fantasy VII.
February 28, 2020 13:57
Thanks for great series of articles! It is worth mentioning that you can already install Docker Desktop on Windows 10 Home as well. This is how I did it: How to run Docker Desktop on Windows 10 Home with WSL2
February 29, 2020 8:38
JetBrains’s new mono font is a lovely complement to this
March 03, 2020 13:23
Docker is very good solution and save a lot of time :)
March 03, 2020 14:23
Your blog is providing very useful information. Thanks for this latest govt jobs

(will show your gravatar icon)
Comment (Some html is allowed: a@href@title, b, blockquote@cite, em, i, li, ol, pre, strike, strong, sub, super, u, ul) where the @ means "attribute." For example, you can use <a href="" title=""> or <blockquote cite="Scott">.  

Live Comment Preview

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.