Fix 'You must be root to run Docker' or Add User to docker Group

Overview

If you see errors like:

• You must be root to run Docker; or
• Got permission denied while trying to connect to the Docker daemon socket

your user likely lacks permission to access the Docker daemon’s UNIX socket at /var/run/docker.sock (owned by root:docker, mode 660). Fix it by adding your user to the docker group or by running Docker in rootless mode.

This guide focuses on Linux (including WSL). Docker Desktop on macOS/Windows uses a VM and typically does not show this error unless you run the CLI inside Linux without proper permissions.

Quickstart (TL;DR)

Run these commands, then re-open your terminal session:

# 1) Ensure the docker group exists
sudo groupadd docker 2>/dev/null || true

# 2) Add your current user to the docker group
sudo usermod -aG docker "$USER"

# 3) Refresh your group membership (or log out and back in)
newgrp docker <<'EOF'
docker run --rm hello-world || docker run --rm alpine:3.20 echo ok
EOF

Notes:

• If you executed the above from a root shell or via sudo, replace "$USER" with your login name or use "$SUDO_USER".
• If newgrp is unavailable, log out and back in to refresh groups.

Step-by-Step: Fix on Linux (rootful Docker)

1. Verify the daemon is installed and running

# Debian/Ubuntu
sudo systemctl status docker || sudo service docker status

# RHEL/CentOS/Fedora
sudo systemctl status docker

1. Check your current groups and the docker group

groups
getent group docker || echo "docker group not found"

1. Create docker group if missing

sudo groupadd docker 2>/dev/null || true

1. Add your user to docker group

# Replace YOURUSER if running from root; otherwise use "$USER"
sudo usermod -aG docker "$USER"    # or: sudo usermod -aG docker YOURUSER

1. Refresh group membership

• Best: log out and log back in.
• Or temporarily: run newgrp docker.

1. Confirm permissions on the socket

ls -l /var/run/docker.sock
# Expect: srw-rw---- 1 root docker ... /var/run/docker.sock

If the group is not docker, fix it:

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

1. Test Docker without sudo

docker info --format '{{.ServerVersion}}'
docker run --rm hello-world

WSL notes:

• If you installed Docker inside your WSL distro, run the above steps inside that same distro and ensure the daemon is started: sudo service docker start.
• If you use Docker Desktop with WSL integration, the docker CLI in WSL connects to a Desktop-managed daemon; you generally don’t need the docker group inside WSL.

Rootless Docker (no docker group needed)

Rootless mode runs the daemon as an unprivileged user. It avoids giving your user root-equivalent access but can have minor feature limits or performance overhead.

Prereqs (example for Debian/Ubuntu):

sudo apt-get update
sudo apt-get install -y uidmap dbus-user-session

Install and start rootless daemon:

# Install rootless support for the current user
dockerd-rootless-setuptool.sh install

# Start the per-user systemd service
systemctl --user enable --now docker

# Point the CLI to your user-level socket and test
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
docker run --rm hello-world

If systemd --user is unavailable, start the rootless daemon manually as documented by your distro’s Docker package.

Minimal Working Example

The following script creates the docker group if needed, adds your user, refreshes your group, and runs a test container.

#!/usr/bin/env sh
set -eu
if ! getent group docker >/dev/null; then
  sudo groupadd docker
fi
sudo usermod -aG docker "${USER}"
# Try to acquire group in this shell
if command -v newgrp >/dev/null 2>&1; then
  newgrp docker <<'EOF'
set -e
docker run --rm hello-world || docker run --rm alpine:3.20 echo ok
EOF
else
  echo "Log out and back in, then run: docker run --rm hello-world"
fi

Troubleshooting and Common Pitfalls

Performance Notes

• Rootful vs rootless:
  • Rootless may use fuse-overlayfs, which is slower than overlay2; expect slight overhead in image IO and filesystem operations.
  • Rootless avoids granting root-equivalent privileges (safer for shared systems).
• Storage driver:
  • Ensure the daemon uses overlay2 on modern kernels for best performance.
• WSL2:
  • Keep project files in the Linux filesystem (e.g., ~/src), not /mnt/c, to avoid slow I/O.
  • Adjust Docker Desktop CPU/memory limits if containers feel sluggish.
• CI runners:
  • Avoid frequent group changes during jobs; use a preconfigured image or rootless mode for consistency.

Security Considerations

• Members of the docker group can effectively gain root by controlling containers and the host via the Docker API. Add only trusted users.
• Prefer rootless Docker when multi-user security is a priority, accepting minor feature/perf trade-offs.

FAQ

• Do I need to reboot after adding my user?

  • No. Log out and back in, or run newgrp docker to refresh group membership.

• Is adding my user to the docker group safe?

  • It grants root-equivalent power via the Docker API. Use only on trusted machines or prefer rootless mode.

• How do I remove myself from the docker group?

  • sudo gpasswd -d "$USER" docker then log out and back in.

• macOS/Windows show this error—why?

  • Typically you’re running a Linux CLI in a VM/WSL without proper setup. Use Docker Desktop or configure permissions inside the Linux environment.

• My docker compose still fails after fixing permissions.

  • Ensure the same environment resolves to the correct daemon. Run docker info and verify Server Version and Docker Root Dir are accessible.