Update 29/05/2020: Microsoft released the Windows 10 May 2020 update, which includes WSL2. WSL2 uses virtualization to run a Linux kernel in a lightweight VM. This allows you to install Docker natively in WSL. For developers, this is a far better experience.
In 2016 Microsoft released Windows Subsystem for Linux, which gives you a full-featured Linux terminal. However, it doesn't come with a Linux kernel (which WSL2 will do), which means that Docker won't work. However, there are workarounds available. In this article, I will explain my own personal setup that makes Docker work on WSL flawlessly by using a VirtualBox virtual machine.
Steps to be taken
- Create a virtual machine with Ubuntu 18.04 LTS
- Install Docker on the virtual machine and modify the Docker service file to expose the API over TCP
- Install Docker on WSL and set environment variable
DOCKER_HOSTto connect to remote Docker API on your VM
Before we start, please make sure you have have the following installed:
- Windows Subsystem for Linux running on Ubuntu 18.04 LTS
- VirtualBox 6
Create a virtual machine with Ubuntu 18.04 LTS
First we start by creating a virtual machine with Ubuntu 18.04 LTS that will host the Docker API.
- Start VirtualBox and create a new virtual machine by clicking "New" button. Give your VM a name that is easy to recognize. Assign at least 2048MB ram, and leave all other settings on default.
- Download the Ubuntu 18.04 LTS ISO.
- Right-click the virtual machine, click on Settings, then click on Storage and click on the label "Empty" with the CD icon in front of it. Then click on the CD icon on the right next to "Optical Drive" and select the Ubuntu ISO.
- While still in the Settings pane, click Network and then Adapter 2. Enable the network adapter and make sure it is attached to Host-only Adapter.
- Start the virtual machine and install Ubuntu.
/etc/netplan/01-netcfg.yamlto enable the use of Adapter by adding an entry for adapter
enp0s8. The file should look like this after editting:
sudo netplan apply and retrieve the IP address of your second adapter by running the
ip a command. Your IP address should be listed in the block of
3: enp0s8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000 link/ether 08:00:27:36:2b:51 brd ff:ff:ff:ff:ff:ff inet 192.168.56.102/24 brd 192.168.56.255 scope global dynamic enp0s8 valid_lft 1042sec preferred_lft 1042sec inet6 fe80::a00:27ff:fe36:2b51/64 scope link valid_lft forever preferred_lft forever
In this case, the IP address of the virtual machine is
Install Docker on the virtual machine
- After the virtual machine has been installed, install Docker according to the instructions on the Docker website.
- Adjust the Docker service definition to expose the Docker API over TCP. Start the editor by entering the following command
sudo systemctl edit --full docker.
- Add the following argument to the line starting with
-H tcp://0.0.0.0:2375. The line starting with ExecStart should now look like this:
Now make sure to execute
systemctl restart docker to make sure Docker starts with the API exposed over port 2375.
Install Docker on WSL
- Open WSL
- Use the same instructions to install Docker as we used for installing Docker on the virtual machine.
echo "export DOCKER_HOST=tcp://<IP of virtual machine>:2375" >> ~/.bashrc && source ~/.bashrcto set the
DOCKER_HOSTenvironment variable to the IP address of your virtual machine by default. Don't forget to add the IP address in this command!
- Now you should be good to. Run
docker run hello-worldto make sure everything is working correctly.
That's it! Now you can use Docker on WSL seamlessly. Other things you can do to make your life even more easier:
- Start the VM in in headless mode so you don't always have an icon for the VM in your taskbar. Right-click the VM, hover over start and click on Headless Start.
- You can even install Docker Compose by following the one-line install command on the Docker documentation.