Resolving Docker Daemon Socket ‘Permission Denied’ on macOS: User Not in Docker Group

Troubleshoot 'permission denied' errors when accessing the Docker daemon socket on macOS. Fix user group issues and common Docker Desktop misconfigurations effectively.

Introduction

As an experienced Systems Administrator and DevOps engineer, one of the most common hurdles developers encounter when working with Docker locally on macOS is the dreaded "permission denied" error when trying to interact with the Docker daemon. While this error is frequently associated with a user not being in the docker group on Linux systems, its manifestation on macOS, which leverages Docker Desktop's underlying Linux virtual machine, requires a slightly different approach to diagnosis and resolution. This guide will clarify the nuances of Docker socket permissions on macOS and provide a robust, step-by-step resolution path.

Symptom & Error Signature

When attempting to execute any docker command, such as checking running containers or building an image, you'll encounter an error message indicating a failure to connect to the Docker daemon socket due to insufficient permissions.

docker ps

Typical error output:

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
See 'docker run --help'.

or

docker: An error occurred trying to connect: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json": dial unix /var/run/docker.sock: connect: permission denied.

Although the path /var/run/docker.sock is often shown in the error, on macOS with Docker Desktop, the actual interaction is abstracted, often involving a proxy socket managed by Docker Desktop itself, rather than a directly exposed Linux socket on the macOS filesystem.

Root Cause Analysis

On traditional Linux installations, the Docker daemon socket (/var/run/docker.sock) is typically owned by root and group-owned by the docker group. Users who need to interact with Docker without sudo must be added to this docker group. Failure to do so results in the "permission denied" error.

However, on macOS, Docker Desktop operates differently:

1. Linux Virtual Machine: Docker Desktop runs a lightweight Linux virtual machine (VM) to host the Docker daemon, containers, and images. The Docker daemon socket (/var/run/docker.sock) does exist within this VM and is managed according to standard Linux practices (owned by root:docker).
2. macOS Host CLI Interaction: The docker CLI tool installed on your macOS host communicates with the Docker daemon running inside the VM. This communication usually happens via a proxy mechanism, often a specific socket managed by Docker Desktop (e.g., ~/Library/Containers/com.docker.docker/Data/docker.raw-socket or via internal IPC), or by setting the DOCKER_HOST environment variable.
3. The "User Not in Docker Group" Misconception: Your macOS user account doesn't directly interact with the /var/run/docker.sock file on the macOS filesystem because it doesn't natively exist there in the same way it does on a Linux host. Therefore, adding your macOS user to a docker group on macOS is irrelevant and will not resolve the issue. The docker group concept applies within the Docker Desktop VM.
4. Actual macOS Causes: The "permission denied" error on macOS typically stems from:
   • Docker Desktop not running: The most common cause. If the VM isn't active, the CLI can't connect.
   • Incorrect DOCKER_HOST: The DOCKER_HOST environment variable might be pointing to an incorrect or non-existent socket, or one that Docker Desktop isn't managing.
   • Corrupted Docker Desktop installation/state: Less frequent, but possible.
   • "Docker in Docker" (DinD) Scenarios: If you are running a container that mounts the host's Docker socket (e.g., -v /var/run/docker.sock:/var/run/docker.sock) and attempts to run docker commands inside that container, then the user inside the container will need to be part of the docker group (or have equivalent permissions) relative to the GID of the mounted socket. This is where the "user not in docker group" issue becomes directly relevant within a macOS Docker setup.

Step-by-Step Resolution

Follow these steps, starting with the most common and simplest solutions for macOS.

1. Verify Docker Desktop Application Status

Ensure that the Docker Desktop application is actively running on your macOS system. The Docker whale icon should be visible in your macOS menu bar, indicating a healthy, running daemon.

• Action: If the icon is not present or shows an error state, launch Docker Desktop from your Applications folder. Wait for the whale icon to turn fully black, indicating it's started and ready.
• Verification: Once running, try docker ps again.

2. Check and Reset DOCKER_HOST Environment Variable

The docker CLI uses the DOCKER_HOST environment variable to determine which Docker daemon to connect to. If this variable is misconfigured or pointing to an invalid location, it will prevent connection. Docker Desktop typically manages this automatically, so an explicit setting might cause issues.

• Action:
  1. Check the current value of DOCKER_HOST:

     echo $DOCKER_HOST
     

  2. If it's set to anything other than empty, or points to /var/run/docker.sock on your macOS host (which is incorrect for Docker Desktop's default operation), unset it for the current session:

     unset DOCKER_HOST
     

  3. If you've configured DOCKER_HOST in your shell's configuration files (e.g., ~/.zshrc, ~/.bashrc, ~/.profile), you'll need to remove or comment out that line to prevent it from being set persistently. After modifying, source your shell config:

     # Example for zsh
     source ~/.zshrc
     

• Verification: Try docker ps again. If it works, ensure the unset or removal is persistent in your shell configuration.

3. Restart Docker Desktop

A simple restart can often resolve transient issues with the Docker Desktop VM or its communication proxy.

• Action:
  1. Click the Docker whale icon in the macOS menu bar.
  2. Navigate to Troubleshoot (often an icon like a bug or cogwheel).
  3. Select Restart Docker Desktop….
  4. Wait for Docker Desktop to fully restart and the whale icon to stabilize.
• Verification: Try docker ps again.

4. Granting Permissions to the docker Group (For DinD or VM Context)

This step is critical only if you are encountering the error within a container that's trying to access the host's Docker socket (e.g., in a "Docker in Docker" setup), or if you've SSHed into the Docker Desktop VM. It is not for your macOS user account directly.

Do NOT attempt to add your macOS user to a docker group on your macOS host. This is a Linux-specific group and will not resolve the issue for your macOS user. This section applies when working inside a Linux environment (like a container or the Docker Desktop VM).

• Scenario: Inside a Docker in Docker Container If your docker run command includes -v /var/run/docker.sock:/var/run/docker.sock and you're getting permission denied inside the running container when executing docker commands, it means the user inside that container lacks the appropriate group membership to match the host socket's GID.

  1. Identify Host Socket GID: On your macOS host, you can determine the GID of the docker group within the Docker Desktop VM by inspecting a temporary container:

     docker run --rm -v /var/run/docker.sock:/var/run/docker.sock alpine sh -c "stat -c '%g' /var/run/docker.sock"
     

     This command will output the GID (e.g., 999).
  2. Create User/Group in DinD Container: When building or running your DinD container, ensure the user inside the container is part of a group with that specific GID.
     • Dockerfile Example:

       FROM docker:stable
       # Get the GID of the docker group on the host (assuming it's 999 for example)
       ARG DOCKER_GID=999
       RUN addgroup --gid $DOCKER_GID docker 
           && adduser --system --ingroup docker someuser
       USER someuser
       

     • Runtime Example (less secure, but for quick testing): You might need to temporarily modify group permissions or run the container as root to perform usermod.

       docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock 
         --group-add $(stat -c '%g' /var/run/docker.sock 2>/dev/null || echo 0) 
         docker:stable sh
       # Inside the container, try `docker ps`. The --group-add maps the host's socket GID.
       

       Exposing your Docker daemon socket to containers grants them root-level access to your Docker host. Only do this for trusted build environments or specific use cases like CI/CD, and never in production if avoidable.

• Scenario: Inside the Docker Desktop VM (Advanced) While uncommon for everyday use, if you've SSHed into the Docker Desktop VM and are trying to run docker commands as a non-root user, you'd add the user to the docker group using standard Linux commands:

  sudo usermod -aG docker $(whoami)
  newgrp docker # Apply group changes without logging out
  

  Then, try docker ps again.

5. Reset Docker Desktop to Factory Defaults (Last Resort)

If all else fails, a complete reset of Docker Desktop can resolve deeply ingrained configuration issues or corrupted states.

Resetting to factory defaults will delete all your downloaded Docker images, stopped containers, and locally stored volumes. Ensure you have backed up any critical data before proceeding.

• Action:
  1. Click the Docker whale icon in the macOS menu bar.
  2. Navigate to Troubleshoot.
  3. Select Reset to factory defaults….
  4. Confirm the reset and wait for Docker Desktop to reinitialize. This can take a few minutes.
• Verification: After the reset, Docker Desktop will restart. Try docker ps to verify the connection. You will need to pull any images and recreate containers.