Docker CLI docker permissions daemon
Yemi Adeyemi Cloud Solutions Engineer

Docker permission denied while connecting to daemon socket

Encountering Docker permission denied means your user lacks access to the daemon socket; this guide explains how to fix it.

What This Error Means

When you execute a Docker command like docker ps or docker run hello-world and receive a permission denied error, it signifies that your current user account does not have the necessary privileges to communicate with the Docker daemon. The Docker daemon is the background process that manages Docker containers, images, volumes, and networks. It typically runs with root privileges.

The error message often looks something like this:

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/info": dial unix /var/run/docker.sock: connect: permission denied.
See 'docker --help'.

This specific message indicates that your user tried to access the Unix socket located at /var/run/docker.sock, which is the default communication endpoint for the Docker daemon, but was denied access by the operating system.

Why It Happens

The Docker daemon runs as a root process to perform its operations securely and effectively. To prevent any arbitrary user from gaining control over your system's containerization capabilities (which essentially translates to root-level access), direct interaction with the daemon's socket is restricted.

By default, the Docker daemon socket (/var/run/docker.sock) is owned by the root user and the docker group, with specific read/write permissions (typically rw-rw---- or 660). This setup ensures that only the root user or users who are members of the docker group can interact with the daemon.

When you run a docker command, the Docker client tries to connect to this socket. If your user is not root and is not a member of the docker group, the operating system's permission model will block your access, resulting in the "permission denied" error.

Another, less common, reason is that the Docker daemon itself isn't running. If the daemon is not active, there's no socket to connect to, or the socket might exist but is non-responsive or has incorrect permissions. While this often manifests as a "connection refused" error, depending on the system state, it can sometimes present as a permission error if the socket file exists but is in an unexpected state.

Common Causes

In my experience, encountering this error almost always boils down to one of a few common scenarios:

  1. User Not in the docker Group: This is by far the most frequent cause. When Docker is installed on a Linux system, a docker Unix group is created. To allow non-root users to run Docker commands without sudo, those users must be added to this group. If you've just installed Docker or created a new user, they won't be in this group by default.
  2. Session Not Updated After Adding User: Even after adding your user to the docker group, the changes won't take effect immediately in your current terminal session. Group memberships are loaded at login. If you don't log out and back in (or use newgrp), your shell still operates with the old group information.
  3. Docker Daemon Not Running: Although less common for a permission denied specifically, if the Docker daemon service is stopped or failed to start, the socket might not be properly available or might have stale permissions, leading to communication issues. I've seen this in production environments after server reboots if Docker wasn't configured to start automatically, or after system updates that interfered with the daemon.
  4. Incorrect Socket Permissions: While rare for a fresh Docker installation, manual intervention or system misconfiguration can sometimes alter the permissions of /var/run/docker.sock. If the file owner, group, or permissions are changed from the expected root:docker 660, then even members of the docker group might be denied.
  5. SELinux or AppArmor Interference: On systems with enhanced security modules like SELinux (e.g., Fedora, CentOS) or AppArmor (e.g., Ubuntu, Debian), these policies can sometimes restrict access to the Docker socket, even if the user is in the docker group. This is more of an advanced edge case but worth considering if standard fixes don't work.

Step-by-Step Fix

Here's a systematic approach to troubleshoot and resolve the "Docker permission denied" error. This sequence addresses the most common causes first.

  1. Check Docker Daemon Status
    First, let's ensure the Docker daemon is actually running. If it's not, fixing permissions won't matter.

    bash sudo systemctl status docker

    • If the output shows "active (running)", the daemon is fine. Proceed to the next step.
    • If it shows "inactive (dead)", "failed", or anything other than "running", you need to start it:
      bash sudo systemctl start docker
      Then, check the status again. If it fails to start, you might need to investigate journalctl -xeu docker for more clues, but this guide focuses on permission issues assuming the daemon can run.

  2. Verify Your User's Group Membership
    Check which groups your current user belongs to. We're looking for docker in the list.

    bash id -Gn

    Look for docker in the comma-separated list of groups. If docker is not present, that's almost certainly the problem.

  3. Add Your User to the docker Group
    If your user is not in the docker group, you need to add it.

    bash sudo usermod -aG docker $USER

    • sudo: Executes the command with superuser privileges.
    • usermod: A command to modify user account information.
    • -aG: Appends the user to the specified supplementary group(s) without removing them from other groups.
    • docker: The name of the group to add the user to.
    • $USER: An environment variable that expands to your current username.

  4. Apply Group Changes (Restart Session)
    The changes made by usermod will not take effect in your current shell session. You must update your session for the new group membership to be recognized. The most reliable way to do this is to log out of your system and log back in. This ensures that your session is fully re-initialized with your updated group memberships.

    Alternatively, for a quick test without logging out (though not recommended for permanent application, as some processes might still use the old group info):
    bash newgrp docker
    This command creates a new shell with the docker group as your primary group. You'll need to exit this subshell to return to your previous shell.

  5. Test Docker Command
    After logging back in (or using newgrp docker), try running a Docker command again without sudo:

    bash docker run hello-world

    If successful, you should see output indicating Docker is working correctly, pulling the hello-world image if not present, and running a small container.

  6. (Optional) Check Socket Permissions
    If, after all the above, you still have issues, it's worth checking the actual permissions of the Docker socket. This is a very rare scenario if Docker was installed correctly, but can be a final sanity check.

    bash ls -l /var/run/docker.sock

    The output should typically look like srw-rw---- 1 root docker ... /var/run/docker.sock. Pay attention to root docker (owner and group) and srw-rw---- (permissions). If it's different, you might need to manually correct it (though this often indicates a deeper system issue or misconfiguration that should be investigated).

    ```bash

    Only if absolutely necessary and you understand the implications

    sudo chown root:docker /var/run/docker.sock

    sudo chmod 660 /var/run/docker.sock

    `` *I generally advise against manually changing these permissions unless you're absolutely sure why they changed, asusermod` is the standard and safest fix.*

Code Examples

Here are the key commands you'll use to resolve this issue, ready for copy-paste:

1. Check Docker daemon status:

sudo systemctl status docker

2. Start Docker daemon (if needed):

sudo systemctl start docker

3. Check your current user's groups:

id -Gn

4. Add your current user to the docker group:

sudo usermod -aG docker $USER

5. Test a Docker command after applying changes (remember to log out/in or use newgrp docker first):

docker run hello-world

6. (Temporary, for current session only) Activate new group membership:

newgrp docker

Environment-Specific Notes

The "permission denied" error with Docker can manifest slightly differently depending on your operating system and environment.

  • Local Development (Linux): This is the primary environment where the usermod -aG docker $USER fix is directly applicable. Whether you're on Ubuntu, Fedora, Debian, or another distribution, the underlying Unix group permission model is consistent. Always remember to log out and log back in for changes to take full effect.

  • Local Development (macOS/Windows with Docker Desktop): Docker Desktop on macOS and Windows uses a virtual machine (VM) to run the Docker daemon. The error permission denied while connecting to daemon socket is highly unlikely to occur in this specific form on the host OS directly.

    • On macOS, the Docker socket is usually at /var/run/docker.sock and access is managed by Docker Desktop itself. If you get a "cannot connect" error, it usually means Docker Desktop isn't running.
    • On Windows (WSL2 integration or Hyper-V), Docker Desktop also manages the daemon in a VM. If you're inside a WSL2 distribution, and Docker Desktop is running and configured for WSL2 integration, you typically don't face this exact permission error. If you do, it might indicate a misconfiguration of the WSL2 integration, or you're trying to connect to a daemon that's not the one managed by Docker Desktop.
    • The primary fix for "cannot connect" on these platforms is to ensure Docker Desktop is running and healthy.

  • Cloud Instances (AWS EC2, Google Cloud, Azure VMs): When provisioning a new Linux VM in the cloud (e.g., an EC2 instance, a GCE VM), Docker might be pre-installed on certain AMIs/images, but your default user (e.g., ec2-user on Amazon Linux, ubuntu on Ubuntu instances) will often not be in the docker group by default. I've often seen junior engineers struggle with this when spinning up a fresh instance. The fix remains the same:
    bash sudo usermod -aG docker $USER
    Replace $USER with ec2-user or ubuntu if you are using sudo su to switch users or are running the command from a script. After running this, a system restart (or logging out and back in) is crucial.

  • CI/CD Pipelines: In CI/CD environments (e.g., Jenkins, GitLab CI, GitHub Actions), build agents often run as specific non-root users. If your pipeline script tries to execute docker commands and the agent user isn't in the docker group, you'll encounter this error.

    • For self-hosted runners, ensure the user running the agent service is added to the docker group on the host machine.
    • For managed services, typically they provide a "Docker-enabled" environment where this is handled, or they use dind (Docker-in-Docker) or similar approaches. If you're encountering the error in a managed CI, double-check their specific documentation for enabling Docker access.

Frequently Asked Questions

Q: Why can't I just use sudo docker every time?
A: While sudo docker would bypass the permission issue, it's generally not recommended for regular use. Firstly, it adds extra typing and can be cumbersome. More importantly, it means every Docker command runs with root privileges. Docker containers, by design, can offer root-level access to the host system. If a container is compromised or misconfigured, running Docker with sudo elevates the risk, as it grants full root capabilities to an attacker or a faulty process. Adding your user to the docker group provides a better balance of convenience and security by granting access only to Docker-related operations without requiring sudo for every command.

Q: Does adding my user to the docker group pose a security risk?
A: Yes, it effectively grants your user root-level privileges to the host. Any user in the docker group can execute commands that can bypass file permissions, gain root access, or escape containers. For instance, you could mount the host's root filesystem into a container and manipulate it. Therefore, only trusted users should be added to the docker group. Treat membership in the docker group with the same caution as sudo access.

Q: I've added my user to the docker group and logged out/in, but it still doesn't work. What next?
A:
1. Double-check Docker Daemon: Re-verify that the Docker daemon is running (sudo systemctl status docker). If it's stopped, start it.
2. Verify Group Membership Again: Run id -Gn to be absolutely sure docker is listed. Sometimes typos happen, or the logout/login wasn't complete.
3. Check Socket Permissions (Advanced): As a last resort, inspect the permissions of /var/run/docker.sock using ls -l /var/run/docker.sock. Ensure it's owned by root:docker and has 660 permissions. If not, there might be a deeper system configuration issue or a Docker installation problem.
4. SELinux/AppArmor: If you're on a system with these security enhancements, they could be interfering. Check system logs (journalctl -xe or dmesg) for any AVC denials related to Docker. This is a more advanced troubleshooting step.

Q: Does docker-compose also require my user to be in the docker group?
A: Yes. docker-compose is a tool for defining and running multi-container Docker applications. Under the hood, it interacts with the same Docker daemon via the same socket (/var/run/docker.sock) as the standard docker CLI commands. Therefore, the permission requirements are identical. If you can't run docker ps without sudo, you won't be able to run docker-compose up either.

(none)