Troubleshoot and fix Docker 'permission denied' errors on Linux — from docker socket and group issues to bind mount UID/GID problems in your homelab.
If you run a homelab, chances are you have bumped into the dreaded "permission denied" error while working with Docker on Linux. Whether you are trying to run docker ps without sudo, mounting a volume into a container, or starting a container that needs to write data back to your host filesystem — permission errors are among the most common issues Docker users face.
This guide walks through the most frequent permission denied scenarios in Docker on Linux, explains what causes them, and shows you how to fix them using real commands verified in official documentation and community-tested solutions.
sudo access on your machineDocker permission errors generally fall into two categories:
This is the error you see when running Docker commands without sudo:
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: dial unix /var/run/docker.sock: connect: permission deniedBy default, the Docker daemon binds to a Unix socket owned by root. Only root or members of the docker group can access it.
This error occurs when a container tries to read or write to a mounted host directory and the user ID (UID) or group ID (GID) inside the container does not match the owner of the host directory. For example:
mkdir: cannot create directory '/var/www/html': Permission deniedThis is the standard fix for the socket permission error. The official Docker documentation recommends creating the docker group and adding your user to it.
sudo groupadd dockerIf the group already exists, you will see a message saying so — that is fine.
sudo usermod -aG docker $USERGroup membership changes are not applied to your current session. You must log out and log back in, or restart your machine. You can also run the following command to re-evaluate your session:
newgrp dockerRun the groups command to confirm your user is now part of the docker group:
groups $USERYou should see docker listed in the output.
docker run hello-worldIf the command runs successfully without sudo, the fix worked.
Note: On Ubuntu 24.04, if you installed Docker via Snap, the docker group may not be created correctly. The recommended approach is to install Docker from the official Docker repository using the apt repository method.
When you mount a host directory into a container using a bind mount (-v or --volume), the container process runs as a specific user (often root inside the container, or a non-root user like www-data, node, or nobody). If that user's UID does not match the owner of the host directory, you get a "permission denied" error.
Start the container and run:
docker exec <container-name> idThis outputs something like:
uid=33(www-data) gid=33(www-data) groups=33(www-data)On your host machine, change the ownership of the mounted directory to match the container user:
sudo chown -R 33:33 ./your-directoryIn your docker-compose.yml, you can pass your host UID and GID to the container:
services:
app:
image: your-image
user: "${UID}:${GID}"
volumes:
- ./data:/app/dataThen create a .env file in the same directory:
UID=1000
GID=1000This tells Docker to run the container process with the same UID and GID as your host user, which resolves permission conflicts for bind mounts.
Note: Not all images support the user directive properly. Check the image's documentation to see what user it expects to run as.If you cannot use the user directive (for example, because the image runs an init system or needs root for certain setup steps), you can build a custom Docker image where the container user has the same UID and GID as your host user.
Example Dockerfile:
FROM node:18
ARG UID=1000
ARG GID=1000
RUN groupmod -g ${GID} node && usermod -u ${UID} -g ${GID} node
USER nodeThen build with:
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t my-custom-image .Sometimes the issue is simply that files in the bind mount source are not readable or writable by the container.
Make files readable for all:
chmod -R a+r ./srcCheck for files owned by root:
ls -la
sudo chown -R $USER:$USER .For specific applications like Elasticsearch that expect a particular UID:
sudo chown -R 1000:1000 ./esdata
sudo chmod -R 775 ./esdataNamed volumes are managed by Docker and do not have the same permission issues as bind mounts because Docker sets the correct ownership automatically.
Instead of:
services:
db:
image: postgres:15
volumes:
- ./pgdata:/var/lib/postgresql/dataUse:
services:
db:
image: postgres:15
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:Docker manages the pgdata volume and its permissions internally.
For environments where you cannot or do not want to grant a user membership in the docker group (which effectively gives root-level access), Docker offers a rootless mode. In rootless mode, the Docker daemon and containers run entirely under a non-root user's namespace. This eliminates the need for the docker group and avoids many permission issues.
Rootless mode requires additional setup steps that are documented in the official Docker documentation.
A less common but very tricky permission error can occur due to a compatibility issue between Docker and containerd. The error message looks like:
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open sysctl net.ipv4.ip_unprivileged_port_start file: reopen fd 8: permission denied: unknownThis is caused by a containerd version incompatibility with the installed Docker runtime. Newer containerd releases introduced changes in sysctl handling that result in this permission error. The fix is to pin containerd to a known good version.
For example, on Ubuntu, Debian, and Proxmox, pinning containerd 1.7.28 has been shown to resolve the issue.
If you are still seeing permission errors after trying the fixes above, run through this checklist:
docker group? Run groups $USER and check.docker exec <container> id to check.ls -la on the mounted path.sudo ausearch -m AVC -ts recentDocker permission denied errors on Linux can be frustrating, but they are almost always solvable by understanding the underlying cause. The most common fix — adding your user to the docker group — resolves the socket permission error quickly. For bind mount permission issues, matching UID/GID between the host and container, using named volumes, or building a custom image are the most reliable solutions.
Remember these key takeaways:
docker group and log out/inuser: "${UID}:${GID}" in docker-compose or fix host directory ownershipWith these solutions in your toolbelt, you can spend less time fighting permissions and more time building your homelab.