Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

usermod cannot add your user to the docker group, or it seems to have no effect

Errorusermod reports that group docker does not exist

Short answer

Create the group if it is missing, then add your user with usermod -aG docker. The -a matters: without it, usermod removes the user from every group not listed. Group changes reach a session only after a new login, or in one shell after newgrp docker.

  • Applies to Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check that the group exists, and compare the groups stored for your account with the ones your current shell has.

    getent group docker
    id -nG
    id -nG "$USER"
  2. 2Match what you see, then jump to its fix

    1. 1usermod says the group does not exist, and getent group docker prints nothingThe docker group does not exist yetFix
    2. 2id -nG "$USER" shows docker, plain id -nG does not, and docker still says permission deniedThe membership exists but your running session does not have itFix
    3. 3after the command you lost sudo or another group you used to haveusermod -G without -a replaced your other groupsFix

What does the error look like?

  • usermod reports that group docker does not exist
  • id does not list docker after the command succeeded

Cause 1 of 3

The docker group does not exist yet

1Check

usermod only accepts groups that already exist. Installing Docker from a source other than the Docker packages, or a minimal image, may not create it.

getent group docker

2Fix

Create the group, then add your user to it. Docker's post-install guide uses exactly these two commands.

sudo groupadd docker
sudo usermod -aG docker "$USER"

3Verify

The account now lists docker.

id -nG "$USER"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The membership exists but your running session does not have it

1Check

Groups are read when a login session starts. The shell you already have keeps the old list.

id -nG
id -nG "$USER"

2Fix

Log out and back in, or start a shell that picks up the new group.

newgrp docker

3Verify

Docker runs without sudo in that shell.

docker run --rm hello-world

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

usermod -G without -a replaced your other groups

1Check

With -G alone, any group the user belongs to that is not in the list is removed. Compare with the groups of a similar account.

id -nG "$USER"

2Fix

Add the missing groups back, and use -a from now on. Run this from an account that still has sudo or from a root console.

sudo usermod -aG sudo,docker "$USER"

3Verify

The account lists every group it needs.

id -nG "$USER"

Confirmed by manpages.ubuntu.com

Did this fix it?

How do I stop it coming back?

  • Always write usermod -aG, never -G alone, when adding to a group.
  • Remember that the docker group grants root-level privileges; add only people who should have that.
  • Put the group creation and usermod in your provisioning script, then log in again before testing.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.