Linux: Add User to Group

On Linux, a user account can be part of one, or more groups. And group membership can give that user certain extra abilities, like:

  • The ability to read certain files, or directories.
  • The ability to run sudo commands.
  • The ability to run docker commands (without needing to run Docker as the root user).

For example, to read the system log on an Ubuntu system (/var/log/syslog) the user needs to be part of the adm group.

To run sudo commands on Debian, or Ubuntu, the user needs to be part of the sudo group. Or part of the wheel group, on an operating system like RHEL.

And to run docker commands, the user needs to be part of the docker group.

Let's see how to add a Linux user account to one, or more of these groups.

💡
Note: To be able to add or remove users from groups, you need to have administrative privileges. You can get those either by logging in as the root user, or by prefixing your commands with sudo (if your current user already has sudo privileges).

And the groups must exist. You can't add a user to a non-existent group.

How to Add a User to a Group On Linux

Let's go through a real example here. The current user is called john. And john can't read this file:

To add the user to an additional group you can use the gpasswd command. The general syntax for gpasswd is:

sudo gpasswd -a user_name group_name

-a is the command-line option that tells the gpasswd utility to add this user to a group.

You'll see other websites mentioning the usermod command to add a user to groups, or the adduser command. But these have some small drawbacks:

  • usermod is slightly less intuitive.
  • If the wrong options are passed to the usermod command you can accidentally remove your user from the previous groups it was part of. And since -aG options are needed for the usermod command, it can be easy to forget one of these two letters, or use a lowercase g instead of the uppercase G required.
  • You can add a user to a group with the adduser command only on Debian-based systems (Debian, Ubuntu, and similar). It won't work on the Red Hat family of operating systems.

gpasswd is intuitive, easier to use, and universal. It works the same way on RHEL, or Ubuntu, or openSUSE. And it has the added benefit that you can also easily remove (delete) users from certain groups, with a simple -d option instead of -a.

So to add a user called john to a group called adm, this is the command you can run:

sudo gpasswd -a john adm

But now, here's a surprise. If you try to read the /var/log/syslog file, this will still fail:

Why is that? Because john is still not part of the adm group in this current login session. Meaning it's important to remember:

💡
After you add a user to a certain group, if that user is still logged in, it has to log out and log in again for the changes to take effect.

In this example, if I take a look at the groups my current user called john is part of, with the groups command:

groups

This is what I'll see:

No adm group in here… yet. But if I log out and log back in, and then run the groups command again:

Now john is part of the adm group. So I will be able to read the syslog file this time:

To see how to add a user to multiple groups on Linux, scroll down to the last sections of this blog.

How to Remove a User from a Group

To remove a user from a group you can use the gpasswd command. The general syntax is:

sudo gpasswd -d user_name group_name

To remove a user called john from a group called adm you can run:

sudo gpasswd -d john adm

And remember that the same thing applies as before: If this user is currently logged in, for this change to take effect, the user has to log out and then log back in.

If the affected user isn't logged in, then the extra step isn't necessary.

Primary Groups vs. Secondary Groups (Login Groups vs. Supplementary Groups)

A Linux user has to be part of what is called a login group. It's a mandatory requirement. Think of it as the "default group" of that user. A user can have only one login group. Further in this section, we'll explain its purpose.

A user can also be part of additional groups, called supplementary groups. These are optional. Which means the user can be part of zero supplementary groups, one group, two, or more.

A login group is sometimes also called a primary group. And a supplementary group is sometimes called a secondary group. To simplify:

  • Login group = Primary group
  • Supplementary groups = Secondary groups

Usually, you'll want to add a user to secondary / supplementary groups. While leaving the primary / login group alone.

To list the groups a user belongs to you can use the groups command. The general syntax is:

groups user_name

So to list the groups for a user called alex, you can run a command like this:

groups alex

What you see after the : colon character is (usually) the primary group. In this case the primary / login group is alex.

You'll often see that a user's primary group has the same name as the user account itself. The user called alex belongs to the primary group called alex. The user called john belongs to a primary group called john. And so on.

That's why you usually don't have to deal with primary groups. They're often unique groups associated with unique users. So they're kind of "set in stone / already paired up". Of course, from time to time, there can be exceptions to this rule.

What's special about the primary group though? Not much. The first thing you'll notice is that whenever you create a file:

touch /tmp/newfile

If you then list files and directories with the ls command and the -l option (to see permissions, and who owns stuff):

ls -l /tmp

You'll notice that the file you created is owned by a user and group. In the screenshot above, the file called newfile is owned by the user called john, and the group called john. Which is john's primary / login group.

Also, whenever you run a program, the process that starts up will run "under" that user and that login group (with the same rights / permissions of that user + login group).

How to Change the Primary (Login) Group of a User

To change the primary group of a user you can run the usermod command (user modify). The general syntax is:

sudo usermod -g group_name user_name

The -g option is what tells usermod to modify the primary / login group. It needs to be a lowercase g, as uppercase G does a different thing.

Note that the arguments expected are in reverse order this time. usermod expects a group name first, and then the user name. Whereas the gpasswd command expected the user name first, and then the group name.

As a real example, to change the primary group of the user called john to a group called staff, you can run this command:

sudo usermod -g staff john

Remember that the same thing applies once again: If the target user is currently logged in, they have to log out and log back in for the change to take effect.

So after I log out, and log back in to the john user account, if I create a new file:

touch /tmp/newfile2

And then list my files again:

ls -l /tmp

Note that the second new file, newfile2 is now owned by the group called staff, the new primary group for the user called john.

💡
Good to know: On some Linux-based operating systems, as soon as you change the primary group, with the usermod command, all files and directories in that user's home directory will have their owners changed. The group owner of files and directories will be changed to the new primary group of that user.

So, in this example, everything in the /home/john/ directory will have the group owner updated to staff. But files created by john in other directories won't have the group owner changed. They'll still be owned by the old primary group called john.

Additional Commands

List Groups of a User

To list the groups a user is part of, use the groups command.

groups user_name_here

List the Primary (Login) Group of a User

To list the primary group of a user, enter this command:

id -gn user_name_here

Two command-line options were used: -g and -n.

  • -g tells the id command to list the "effective group". Which means the primary group, for our purposes.
  • And -n tells the command to display group names instead of group numbers (IDs).

Add User to Multiple Groups

To add a user to multiple groups, you can run the usermod command.

For example, to add a user called john to these supplementary groups: games, docker, www-data, and operator, you would run this command:

sudo usermod -aG games,docker,www-data,operator john
💡
All groups listed must already exist on the system. You can't add a user to non-existent groups.

The -a option tells usermod to append / add this user to other groups. -G tells the command that the user will be added to secondary groups.

Very important:

  • Both options, -a, and -G need to be used.
  • -G needs to be an UPPERCASE G and not lowercase g. As lowercase g has an entirely different effect.
  • The group names have to be separated by , comma characters AND NO spaces should be added before, or after these commas.

Not following these rules can lead to unexpected results. Like accidentally removing the user from old groups it was part of, or similar unwanted actions.

Now you can see why I recommended gpasswd instead of usermod at the beginning of this blog. It's easier to use, and less prone to accidents.

But gpasswd is limited to working with one group at a time. Only usermod can work with multiple groups in one shot, so that's why it was included here.