Permission Denied While Trying to Connect to the Docker Daemon Socket
Add your user account to the docker security group: sudo usermod -aG docker $USER and log out/in or run newgrp docker.
Root Cause Analysis
This error occurs when a non-root user executes a Docker command (or runs Python code using the docker SDK) on Linux, and the user lacks read/write permissions to the Unix domain socket /var/run/docker.sock.
1. Unix Socket Permissions on /var/run/docker.sock
The Docker daemon (dockerd) binds to the Unix socket /var/run/docker.sock. By default on Linux systems, this socket is owned by root:docker with permissions 0660 (rw-rw----). Users not belonging to the docker group receive Permission denied.
2. New Group Membership Not Activated in Shell Session
Running sudo usermod -aG docker $USER updates group definitions, but active terminal shell sessions do not inherit new group tokens until re-login or newgrp docker.
3. Docker-in-Docker or CI/CD Container Permissions
Mounting /var/run/docker.sock into a container running as a non-root user (e.g. USER node or USER jenkins) fails unless group IDs match.
4. Docker Service Not Running
If the Docker daemon service crashed or is disabled, socket connections fail.
Reproduction Code (MCVE)
# **Note de reproductibilité :** Dépendant des permissions du système hôte Linux.
raise PermissionError('Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock')
Solution 1: Add User to the Docker Group
Add the current user to the docker group and apply changes in the active shell.
import os
user = os.getenv('USER', 'ubuntu')
print('Execute in terminal:')
print(f'sudo usermod -aG docker {user}')
print('newgrp docker')
print('# Then test with: docker ps')
Solution 2: Configure Socket Permissions in CI/CD Environments
In automated runners, grant socket group permissions or configure rootless Docker.
print('CI Runner permission fix:')
print('sudo chmod 666 /var/run/docker.sock # (For isolated runner VMs only)')
A dangerous security mistake is setting chmod 777 /var/run/docker.sock permanently on production shared servers. Access to the Docker socket is equivalent to root access on the host. Always manage access via the docker group. Edge cases occur with WSL2 on Windows: ensure Docker Desktop integration is enabled for your specific WSL distribution in Docker Desktop settings. Contrast this error with Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?, which indicates the daemon is stopped.