Fixing ‘Docker daemon socket permission denied’ on Windows WSL2 Ubuntu

Resolve 'permission denied' errors when interacting with the Docker daemon socket in WSL2 Ubuntu by correctly adding your user to the Docker group. A crucial fix for Docker users on Windows.

Introduction

As a seasoned SysAdmin and DevOps engineer, one of the most common hurdles I've seen developers face when working with Docker on Linux environments, especially within a Windows Subsystem for Linux (WSL2) Ubuntu instance, is the dreaded "permission denied" error when trying to interact with the Docker daemon. This typically manifests when a user attempts to run docker commands without sudo and is met with an error indicating they can't access the Docker Unix socket. This guide will walk you through the precise steps to resolve this, ensuring your WSL2 Ubuntu environment is perfectly configured for Docker development.

Symptom & Error Signature

When you attempt to execute any docker command, such as docker ps, docker images, or docker run, without elevated privileges (i.e., not using sudo), you will encounter an error message similar to the following:

docker ps

docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json": dial unix /var/run/docker.sock: connect: permission denied.
See 'docker --help'.

This error clearly indicates that your user account lacks the necessary permissions to communicate with the Docker daemon via its Unix socket.

Root Cause Analysis

The Docker daemon runs as a root process on your Linux system. For security reasons, it exposes its API through a Unix socket located at /var/run/docker.sock rather than over a network port by default. This socket is typically owned by root and belongs to the docker group, with permissions set to allow read/write access only to root and members of the docker group.

When you install Docker, a new Unix group called docker is created. For non-root users to interact with the Docker daemon without needing sudo for every command, they must be added to this docker group. If your user account is not a member of the docker group within your WSL2 Ubuntu instance, you will be denied permission to access /var/run/docker.sock, leading to the error message described above.

This scenario is particularly common in WSL2 because, while Docker Desktop on Windows might handle the daemon management, the user's permissions within the WSL2 distribution itself still need to be correctly configured for seamless interaction.

Step-by-Step Resolution

Follow these steps to correctly add your user to the docker group and resolve the permission issue.

1. Verify Docker Daemon Status and Socket Permissions

First, let's confirm that the Docker daemon is actually running and check the permissions of its socket file.

# Check if the Docker service is active in your WSL2 Ubuntu instance
sudo systemctl status docker

# If systemctl is not available (e.g., older WSL versions or custom setup), use:
# sudo service docker status

# Inspect the permissions of the Docker socket
ls -la /var/run/docker.sock

You should see output similar to this for the ls -la command:

srw-rw---- 1 root docker 0 Nov  1 14:30 /var/run/docker.sock

The srw-rw---- indicates a socket (s) with read/write permissions for the owner (root) and the group (docker). If your user is not in the docker group, you won't have access.

2. Identify Current User and Groups

Next, identify your current user and the groups it belongs to.

id -Gn $USER

This command will list all groups your current user ($USER) is a member of. You'll likely notice that docker is not among them.

3. Add User to the docker Group

Now, add your current user to the docker group. Replace $USER with your actual username, or simply use $USER as it's an environment variable representing your current user.

sudo usermod -aG docker $USER

The -a flag means "append" and -G specifies the group. This command modifies the user's group memberships without removing them from existing groups.

After adding your user to the docker group, the changes will not take effect immediately in your current shell session. You must either log out and log back in, or restart your WSL2 Ubuntu instance and open a new terminal session. Simply closing and reopening the terminal window might not be sufficient if the session maintains previous environment variables.

To restart your WSL2 instance from PowerShell (on Windows):

wsl --shutdown

Then, reopen your Ubuntu terminal in WSL2.

4. Verify Group Membership and Test Docker

After restarting your WSL2 instance or logging back in, verify that your user is now correctly listed as a member of the docker group.

id -Gn $USER

You should now see docker included in the list of groups.

Finally, test if you can run Docker commands without sudo:

docker run hello-world

If everything is configured correctly, Docker will pull the hello-world image (if not already present) and run a simple container, printing a "Hello from Docker!" message.

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:d131f51397e541482e1818165567a506649886aebf5e9333a670353b58bc7530
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output back to the Docker client, which
    sent it to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Congratulations! You have successfully resolved the Docker daemon socket permission denied error in your WSL2 Ubuntu environment.

5. (Optional) Advanced Troubleshooting: Docker Daemon Not Running or Socket Missing

If, after completing the above steps, you still face issues or if ls -la /var/run/docker.sock showed that the socket file doesn't exist, it likely indicates that the Docker daemon itself is not running within your WSL2 instance or that Docker Desktop integration isn't properly configured for that specific distribution.

1. Start the Docker Daemon (if running directly in WSL2):

   sudo service docker start
   # Or, for systems with systemd enabled in WSL2 (newer Ubuntu versions in WSL2)
   # sudo systemctl start docker
   

   Then re-check ls -la /var/run/docker.sock and retry docker ps.

2. Verify Docker Desktop Integration: If you're using Docker Desktop on Windows, ensure that the WSL2 integration is enabled for your specific Ubuntu distribution.

   • Open Docker Desktop settings.
   • Navigate to "Resources" -> "WSL Integration".
   • Make sure the toggle next to your Ubuntu distribution is turned "On".
   • Sometimes restarting Docker Desktop and then your WSL2 instance can help re-establish this connection.

By following this comprehensive guide, you'll ensure a smooth and permission-free Docker experience within your Windows WSL2 Ubuntu setup.