Add a user to a group in Linux

Add an existing Linux user to a group with usermod -aG or gpasswd, check the result with id, understand why a new login is needed, and remove a user from a group.

  • Beginner
  • Linux VPS
  • 4 min read

By RunRacks Team · Published

Groups are how Linux shares access. Put a user in the sudo or wheel group and they can administer the server; put them in www-data or docker and they can work with web files or containers. This guide shows how to add a user to a group safely, check it worked and remove them again.

Before you start

  • A RunRacks Linux VPS with Ubuntu 22.04 or 24.04, Debian 12, or AlmaLinux or Rocky Linux 8 or 9.
  • An SSH session as root or a sudo user.
  • The user already exists. If not, create it first with Add a new user on Linux.

Primary and secondary groups

Every user has:

  • One primary group, stored in /etc/passwd. New files the user creates belong to this group. On Ubuntu, Debian, AlmaLinux and Rocky it is usually a private group with the same name as the user.
  • Any number of secondary (supplementary) groups, stored in /etc/group. These grant extra access.

Almost always, you want to add a secondary group. See the current groups first:

Terminal
id deploy
Text
uid=1001(deploy) gid=1001(deploy) groups=1001(deploy)

Create the group if needed

Check whether the group exists:

Terminal
getent group developers

If it prints nothing, create it:

Terminal
sudo groupadd developers

Add the user with usermod

Terminal
sudo usermod -aG developers deploy
  • -G sets the list of secondary groups.
  • -a means append. It keeps the groups the user already has.

To add several groups at once, separate them with commas and no spaces:

Terminal
sudo usermod -aG developers,www-data deploy

Or add the user with gpasswd

gpasswd changes one group at a time and cannot wipe other memberships by accident:

Terminal
sudo gpasswd -a deploy developers
Text
Adding user deploy to group developers

On Ubuntu and Debian, sudo adduser deploy developers does the same thing.

Make the change take effect

Group membership is read when a session starts. A user who is already logged in keeps the old list until they log in again. That is why id shows the new group but groups in their own shell does not.

Choose one:

  • Log out of SSH and log back in. This is the cleanest option.
  • Start a subshell with the new group active:
Terminal
  newgrp developers

This only affects that one shell.

Services also need a restart. If you add a service account to a group, restart the service so it picks up the new membership:

Terminal
sudo systemctl restart nginx

Give admin rights

Admin access is just a group membership.

Ubuntu and Debian:

Terminal
sudo usermod -aG sudo deploy

AlmaLinux and Rocky Linux:

Terminal
sudo usermod -aG wheel deploy

Test it after a fresh login with sudo whoami, which should print root. For a full setup, see Create a sudo user on Linux.

Remove a user from a group

The safest way is gpasswd -d:

Terminal
sudo gpasswd -d deploy developers
Text
Removing user deploy from group developers

On Ubuntu and Debian you can also use sudo deluser deploy developers. Both leave the user's other groups untouched. As before, the change applies at the next login.

Change the primary group (rarely needed)

If you really need new files to belong to a different group by default, change the primary group with lowercase -g:

Terminal
sudo usermod -g developers deploy

Existing files keep their old group. Most of the time a shared folder with the setgid bit is a better answer than changing primary groups.

Check it works

Terminal
id deploy
getent group developers

id should list the new group, and getent group should show deploy among the members:

Text
developers:x:1003:deploy

Then log in as the user in a new session and run groups. The new group must appear there too.

Troubleshooting

  • `id deploy` shows the group but the user still gets "Permission denied": the user's session is older than the change. Log out and in again, or restart the service that runs as that user.
  • The user lost sudo after you added a group: -a was missing. Log in as root or through the browser console in your Dashboard and add sudo or wheel back with usermod -aG.
  • "usermod: group 'developers' does not exist": create it first with groupadd, or check the spelling with getent group.
  • "gpasswd: user 'deploy' is not a member of 'developers'": the user is only in that group as a primary group, or not at all. Check with id deploy.

Next steps

Was this guide helpful?

Still stuck?

Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.

Linux VPS

Deploy a Node.js app with PM2 behind Nginx

Install a Node.js LTS release, keep your app running with PM2 across crashes and reboots, and serve it through Nginx with HTTPS.

  • Intermediate
  • Linux VPS
  • 3 min read

Linux VPS

Create an SFTP-only user limited to one folder

Give someone file access over SFTP without a shell, locked inside one folder. Configure internal-sftp with a Match block, set the chroot ownership right and test with WinSCP.

  • Advanced
  • Linux VPS
  • 5 min read