Setting up docker within WSL

Kehinde Hussein, Fasunle — Sat, 28 Jun 2025 09:28:43 +0000

Why not docker desktop?

Docker desktop is the easiest way to get started with docker on windows. However, recently there have been a number of issues. Whenever docker or windows OS is updated, docker desktop fails to start due to its inability to start the docker daemon process.

You can verify this by running:

docker version

You see the following:

This shows that the client is installed correctly but the server (docker daemon) is not running.

I face these issues almost every time.

I explored different solution including:

Uninstalling and reinstalling with admin privileges.
Downloading a new version and installing it
Removing all Docker folders in %appdata%\Docker directory

None of the above was able to fix the issue.

I decided to try a new approach

Installing the docker server withing the WSL. I check the documentation of docker here:
https://docs.docker.com/engine/install/ubuntu/

I started as follows:
First open your WSL terminal. Search wsl from your windows search box, and enter.

The following will be done on your wsl terminal.

Step 1: Uninstall any previously installed containerd services

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

Step 2: Update apt and install docker

# Add Docker's official GPG key:
sudo apt-get update
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 "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Step 3: Install docker packages e.g docker-compose etc

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 4: check if your installation is complete within your WSL

docker version

You should see something like:

Now your docker has been set up within the windows subsystem for linux (WSL).

Accessing docker from outside wsl environment

This is great! However, you cannot access this within your local desktop or computer terminal.Let us work around this.

You likely use gitbash already, so we will set alias within .bashrc file such that whenever you type docker, it would invoke the one within the wsl.

Locate the file ~/.bashrc using for example vim:

vim ~/.bashrc

Add the following line to the .bashrc script and save

alias docker="wsl docker";

You must ensure that you have uninstall your docker desktop so as to prevent conflict.

Also, close and reopen the bash terminal. This should now give you the same response as above when you executed:

docker version

Add GUI for a complete set up

Again, you can now run docker as you would with docker desktop except that there is no graphic User Interface (GUI). Let us add this next.

run this command to start a container which will serve as our GUI and can be opened from the browser via port 9090.

docker volume create portainer_data
docker run -d -p 9090:9000 --name=portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce

NOTE: if port 9090 is not free on your device, kindly remove the image by running:

docker rm portainer

Change the port and rerun the command:

e.g:

docker run -d -p 9999:9000 --name=portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce

Then open localhost: e.g localhost:9090 on your browser.

You now have a complete docker setup for your device.

Note that if you run this for the first time, it will ask you to add username and password with which you will login subsequently.

DEV Community: Kehinde Hussein, Fasunle