Add a user to a group in Linux: usermod -aG, gpasswd and adduser

Short answer: to add an existing user to a group on Linux, run sudo usermod -aG GROUP USER, for example sudo usermod -aG docker alice. The -a (append) keeps the user’s other groups; without it, -G replaces them. The new group applies from the user’s next login, so log out and back in, then check with id alice.

sudo usermod -aG docker alice     # add alice to docker, keep her other groups
id alice                          # the list should now end in ...,docker
# alice logs out and back in (or runs: su - alice) before the group takes effect

The commands and flags below follow the man pages of the shadow tools (usermod, gpasswd, groupadd, newgrp, version 4.13 as shipped in Debian 12) and of Debian’s adduser 3.134. usermod and gpasswd behave the same on Ubuntu and Rocky Linux.

Cheat sheet: add, check and remove group membership

Why -a matters: -G on its own replaces the group list

-G takes the complete list of supplementary groups the user should have. The man page is blunt about it: if the user is currently a member of a group which is not listed, the user will be removed from the group. -a changes that to “add these to the list”. The difference in practice:

id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice),27(sudo),100(users)

sudo usermod -G docker alice      # wrong: no -a
id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice),988(docker)

alice is now in docker, and no longer in sudo. If alice was the only admin account and root has no password, that is a lockout. The shadow tools keep the previous version of the group file as /etc/group-, so the damage of the last change is easy to see and undo while you still have a root shell:

sudo diff /etc/group- /etc/group     # lines with < are the old state
sudo usermod -aG sudo,users alice     # put the lost groups back

Without any working sudo account, you need root by another route: su - with the root password, or the provider’s console, which gives you a login prompt on the machine itself. The same trap exists in gpasswd -M alice,bob docker, which sets the complete member list of a group and drops everyone not named.

usermod, gpasswd or adduser: which one?

• usermod -aG works everywhere and takes several groups in one go, separated by commas with no spaces. It prints nothing when it succeeds.
• gpasswd -a USER GROUP adds one user to one group and confirms it with Adding user alice to group docker. There is no -a to forget, which makes it the safer habit in scripts and documentation. Note the order: user first, then group, the reverse of how most people say it.
• adduser USER GROUP is Debian’s friendly wrapper and exists on Debian and Ubuntu only. Called with two names, it adds an existing user to an existing group. On Rocky Linux, adduser is just another name for useradd and does not do this. On Alpine, the BusyBox form is addgroup alice docker.

How do I check which groups a user is in?

id alice            # UID, primary group and all supplementary groups
groups alice        # just the names
getent group docker # one group and its listed members
id                  # the groups of THIS session, which may be older

$ id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice),27(sudo),988(docker)
$ getent group docker
docker:x:988:alice

id alice reads the account database, so it shows the change at once. id without a name shows what your current shell actually has. When the two disagree, the shell is older than the change, which is the next section. The member list in getent group leaves out users for whom this is the primary group; listing users and groups explains that and the other columns.

Why does the new group not work yet?

A process gets its group list when the login starts, and every program started from it inherits that list. Changing /etc/group does not reach processes that are already running, so the classic symptom is docker ps still answering permission denied right after usermod. Ways to pick up the new group:

• Log out completely and back in. Over SSH that means a new connection. If you use connection sharing (ControlMaster in ~/.ssh/config), close the master first with ssh -O exit HOST, otherwise the “new” session reuses the old one.
• su - alice starts a fresh login inside the terminal you already have.
• newgrp docker starts a new shell in which docker is the active group. It helps only that shell and what you start from it; exit takes you back. For a single command, sg docker -c "docker ps" does the same without the extra shell.
• tmux and screen keep the old groups. Their server process started before the change, and every new window is a child of it. Close all sessions (tmux kill-server) and start again from a fresh login.
• Services read groups at start. A service that runs as the user, such as a CI runner or a PHP-FPM pool, keeps its old group list until sudo systemctl restart NAME.

How do I create a new user and add it to groups?

On Debian and Ubuntu, adduser creates the user interactively: home directory, default shell files from /etc/skel, /bin/bash and a password prompt. Then add the groups:

sudo adduser alice                 # asks for a password and optional details
sudo usermod -aG sudo,docker alice

useradd is the low-level tool that every distribution has. It can set the groups at creation time, where -G without -a is fine because there is nothing yet to replace. It does not ask for a password, so set one or install an SSH key before the first login:

sudo useradd -m -s /bin/bash -G sudo alice     # wheel instead of sudo on Rocky Linux
sudo passwd alice

useradd vs adduser in one paragraph: on Debian and Ubuntu, useradd without options creates no home directory, sets /bin/sh as the shell and leaves the password locked, so always pass -m -s /bin/bash and set a password or key. adduser does all of that for you. On Rocky Linux the two names are the same program, and the home directory and bash are already the defaults. In both families a new user normally gets a private primary group with its own name. Giving the account admin rights, testing them and locking down root login is a guide of its own: create a sudo user.

How do I create a group for a shared folder?

A group of your own is the clean way to let several users work in one directory without giving any of them more than they need:

sudo groupadd developers
sudo usermod -aG developers alice
sudo usermod -aG developers bob

sudo mkdir -p /srv/project
sudo chgrp developers /srv/project
sudo chmod 2775 /srv/project       # the 2 is setgid: new files inherit the group

The setgid bit on the directory makes every new file and subdirectory belong to developers instead of the creator’s private group. Whether the others can also write to those files depends on the creator’s umask: with the common 022, new files are group-readable only, with 002 they are group-writable. groupadd -g 2000 developers fixes the group ID, which matters when the same group must match on several servers, on NFS or inside containers. For handing existing files to the group, see the chown command.

How do I remove a user from a group?

sudo gpasswd -d alice docker      # prints: Removing user alice from group docker
sudo deluser alice docker         # Debian, Ubuntu
sudo usermod -rG docker alice     # only if usermod --help lists -r (Debian 12's 4.13 does)

Removal has the same timing as adding: sessions that are already running keep the group until they end. To take access away now, end the user’s sessions with sudo loginctl terminate-user alice and restart any service that runs as that user. sudo groupdel developers deletes a whole group; it refuses while the group is still some user’s primary group.

Which groups matter on a server?

Two of these deserve care. Treat the docker group exactly like sudo: anyone in it can become root on the host, which is why docker: permission denied on the daemon socket recommends it only for accounts you would trust with sudo anyway. And with www-data, decide which direction you need. Adding your deploy user to www-data lets it edit files the web server owns; the safer layout is the reverse, files owned by the deploy user with group www-data and mode 640 (directories 750), so the web server can read the site but not rewrite it. Never add www-data itself to sudo. And someone who only needs to read logs with journalctl belongs in adm or systemd-journal, not in sudo.

Common errors and what they mean

• usermod: group 'docker' does not exist. The group has to exist first. Create it with groupadd, or install the software that brings it: Docker’s packages create the docker group.
• usermod: user 'alice' does not exist. A typo, or the order is reversed: usermod wants the group after -aG and the user last, gpasswd -a the user first.
• usermod: Permission denied. followed by cannot lock /etc/passwd; try again later. You ran it without root. Put sudo in front. If you are root and still see the lock message, another account tool is running or crashed and left a lock file such as /etc/passwd.lock behind.
• usermod: command not found right after su. Plain su keeps your user’s PATH, which lacks /usr/sbin on Debian. Use su -.
• Added, and it still does not work. Compare id with id alice. If only the second shows the group, the session is older than the change; see above.

On a VPS or dedicated server

A fresh Linux server usually starts with root as its only login, so the first group change you make is the admin group for your own account, followed by whatever your stack needs: docker for the deploy user, a shared group for a project directory. Keep the admin and docker groups as short as you can, check them now and then with getent group sudo docker, and make every change with -aG or gpasswd -a. If one still goes wrong on a VMHeaven VPS, the VNC console in the panel gives you a login prompt that needs neither SSH nor sudo. As long as root has a password, that is enough to put the groups back from /etc/group-.

Frequently asked