Romain BruyèreUsing Docker on Windows has grown more challenging over the past few years. This guide aims to walk you through the process, from start to finish, to help you make the most of Docker on Windows without having to install Docker Desktop.
To use Docker without Docker Desktop, you’ll need to:
- Install WSL2, to serve as a runtime environment for Docker Engine
- Install Docker Engine inside WSL2, to be able to run containers
- Expose Docker Engine to be able to access it from Windows
- Install Docker command-line tools on Windows
Install WSL2
WSL2, or the Windows Subsystem for Linux, allows you to run a Linux distribution on Windows. To install it with the default Ubuntu distribution, open a terminal in administrator mode and use the following command:
wsl --install
If you want to install a different Linux distribution instead of the default Ubuntu, you can list the available distributions and then install your preferred one using the following command:
wsl --list --online
wsl --install -d <DistroName>
It’s not mandatory, but depending on your setup, you might find it helpful to limit the resources allocated to WSL2. To do this, create a file named .wslconfig in your user folder. You can quickly access your user folder by typing %UserProfile% in the File Explorer's search bar.
Here’s an example of what a .wslconfig file might look like:
[wsl2]
memory=4GB
processors=2
After installing WSL2, you can start it by typing wsl in a terminal, or by launching the WSL program from your Windows Start menu. Once WSL2 is open, update your Linux distribution to ensure all packages are up to date with the following command:
sudo apt update && sudo apt upgrade
To learn more about configuring WSL2 distributions and resource allocation, refer to the following sources.
Sources:
https://learn.microsoft.com/en-us/windows/wsl/install
https://learn.microsoft.com/en-us/windows/wsl/wsl-config
Install Docker Engine on WSL2
Next, let’s install the Docker Engine, which is the core component that runs Docker containers. The following two blocks of commands will first add the Docker apt repository and then install Docker. You can execute them directly in the WSL2 terminal.
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Now that Docker is installed, let’s confirm that it’s working correctly. The following command will download and run the hello-world container. If the installation was successful, it should display a confirmation message and then exit.
sudo docker run hello-world
By default, you need to use sudo with Docker commands for elevated permissions. To run Docker without sudo, you can create a group docker for Docker users and add your current user to that group.
sudo groupadd docker
sudo usermod -aG docker $USER
On some distributions, the Docker group is created by default. You only need to add your user to this group to have the permission to run Docker without sudo. The Docker group is automatically managed by the Docker Engine, ensuring that only users in this group have permission to run Docker commands. After adding yourself to the Docker group, exit WSL2, then restart it, or simply log out and back in. Once you re-open WSL2, you should be able to use Docker without the need for sudo.
docker run hello-world
If you’re using a non-default WSL distribution, like a custom Linux distro, Docker might not start automatically when you launch WSL. To ensure Docker starts every time you open WSL, use the following commands:
sudo systemctl enable docker.service
sudo systemctl enable containerd.service
Sources:
https://docs.docker.com/engine/install/ubuntu/
https://docs.docker.com/engine/install/linux-postinstall/
Expose Docker Engine on Windows
To access the Docker Engine from Windows, you’ll need to configure remote access for Docker. There are two ways to do this, by modifying the docker daemon, or by overriding systemd launch configuration.
With daemon.json
For that method, you need to create or edit the /etc/docker/daemon.json file inside WSL2. Navigate to the /etc/docker directory and use the following command to edit the file:
vi daemon.json
# In vi,
# You press the key 'I' to enter in insert mode and be able to edit the file
# You press the key 'ESC', once you have finished inserting
# You press the keys ':wq' to save and quit editing
Then add this content to the file:
{
"hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}
With systemd
With that method, to override the systemd launch configuration for the Docker service, you can create or edit a systemd override file by using the following command:
sudo systemctl edit docker.service
Then add, or modify, the following lines
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375
Be sure to only use one of the two methods, not both. No matter the method you choose, for these changes to be applied, you will need to restart the Docker service.
sudo systemctl daemon-reload
sudo systemctl restart docker.service
To confirm that Docker is exposed on Windows, visit the URL http://localhost:2375/version. If you receive a response showing the current version of the Docker Engine, it means the exposure is successful.
Create the link between WSL2 andWindows
To ensure that the Docker agent on Windows can detect the Docker Engine installed on WSL2, you need to establish a connection between the two by adding a DOCKER_HOSTenvironment variable on Windows. It specifies the address of the Docker Engine and determines where Docker commands will be sent.
Depending on the configuration of your computer, and the activation of IPv6, you can set it to tcp://localhost:2375 or tcp://[::1]:2375.
Sources:
https://docs.docker.com/config/daemon/remote-access/
https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f
Install Docker CLI on Windows
The final step is to install the Docker CLI on Windows. The CLI consists of several executable files that must be placed in specific locations within the Windows filesystem.
First, you must install the main executable. Create a folder for the installation wherever you’d like in the Windows filesystem, and then add that folder to your PATH. Next, visit https://download.docker.com/win/static/stable/x86_64/, download the latest version, and unzip the executables into the folder you just created.
You should now be able to run most Docker commands. To test it, try executing:
docker version
If it doesn’t work, one advice is to try with the other value for the DOCKER_HOST environment variable.
Plugins, Buildx and Compose
Simply installing the main executable usually isn’t enough if you want to use all of Docker’s features. The builder included with the executable is the legacy builder, and the docker compose command will be unavailable. To access those additional features, you'll need to install some plugins.
In your user folder, accessible by typing %UserProfile% in the File Explorer's search bar, create the folder tree .docker\cli-plugins\ if it doesn’t exists already.
To install the newest builder, download the latest version of the buildxplugin by visiting https://github.com/docker/buildx/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with windows-amd64.exe, like buildx-v0.14.0.windows-amd64.exe. Place the downloaded file in the cli-plugins folder you created earlier, and rename it to docker-buildx.exe. Now, the command docker build will automatically use the new builder.
To install docker compose tool, download the latest version of the plugin by visiting https://github.com/docker/compose/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with windows-x86_64.exe, like docker-compose-windows-w86_64.exe. Place the downloaded file in the cli-plugins folder you created earlier, and rename it to docker-compose.exe. Now, we can use the command docker compose.
The installation is finished ! 🥳
I hope everything is working fine ! Don’t forget to start WSL2 when you want to use Docker.
Sources:
https://docs.docker.com/engine/install/binaries/#install-server-and-client-binaries-on-windows
https://github.com/docker/buildx/releases
https://github.com/docker/compose/releases
