VMware ESXi and vSphere Cluster Management

How to Create Linux Groups with addgroup

Learn how to create Linux groups with addgroup, assign a GID, add existing users, verify membership, and troubleshoot common errors.

Linux groups organize user accounts for shared permissions and access control. Instead of granting access to each user separately, you can assign users to a group and give that group permission to use files, directories, devices, or other resources.

This lesson focuses on addgroup, a user-friendly command commonly available on Debian- and Ubuntu-based systems. You will create a group named test_group, optionally request GID 2000, add the existing user jowilliams, and verify the result.

What Linux groups are used for

A group is a named collection used by Linux to apply permissions and access rules to multiple users. For example, a shared project directory can belong to a group named developers. Every user in that group can then receive the permissions assigned to the group.

Each group has two important identifiers:

• Group name: The human-readable name, such as test_group.
• GID: The numeric group ID associated with the group, such as 2000.

Linux uses the GID internally when checking ownership and permissions. The group name makes administration easier for people, while the numeric ID provides the underlying identity.

A newly created group has no supplemental user members by default. Creating test_group does not automatically add existing users to it. Membership must be assigned separately.

Primary and supplementary groups

A user's primary group is the main group associated with the account. It is typically used as the group owner for files the user creates. A supplementary group is an additional membership granted beyond the primary group.

Adding jowilliams to test_group normally grants supplementary membership. It does not change the user's primary group and does not create the user account.

addgroup, groupadd, and adduser

addgroup is a higher-level, user-friendly administration command. On systems that provide it, it commonly acts as a front end to the lower-level groupadd utility.

Command availability and option syntax vary between Linux distributions. Debian and Ubuntu commonly provide addgroup and adduser, while other distributions may primarily document groupadd and usermod. Always check the local help output when an option is rejected.

Create a group with an automatically selected GID

To create test_group and allow the system to select an available GID, run:

sudo addgroup test_group

Administrative privileges are normally required because this changes the system's account database. When no GID is specified, the local administration tool selects an available GID according to the distribution's policy and configuration.

The command creates the group, but it does not add any supplemental members. If the name is already in use, the command should fail rather than create a duplicate group name.

Create a group with a specific GID

A fixed GID can be useful when permissions must remain consistent across systems. This may matter for shared storage, replicated files, containers, or several servers that need to interpret the same numeric group ownership consistently.

To request GID 2000 for test_group, use:

sudo addgroup --gid 2000 test_group

The requested GID must not already be assigned unless the relevant tool and options explicitly support an exceptional operation. Check the number before creating the group:

getent group 2000

No output usually means that no entry was found through the configured group databases. Output means that a group already owns that GID, so choose another unused value unless the existing mapping is intentionally required.

The exact option may differ on some systems. If --gid is rejected, inspect the installed command:

addgroup --help

A common lower-level equivalent is:

sudo groupadd -g 2000 test_group

Add an existing user to the group

After the group exists, add the existing account jowilliams as a supplementary member:

sudo adduser jowilliams test_group

This command changes group membership. It does not create jowilliams. The account and the target group must already exist, and the names must be spelled exactly.

On systems where adduser is unavailable or behaves differently, use the lower-level form:

sudo usermod -aG test_group jowilliams

The -a means append. Omitting it while using -G can replace the user's existing supplementary group list, which may remove access the account already had.

Refresh the user's active session

Group membership is normally established when a login session starts. If jowilliams was already logged in, the current session may still have its old group credentials.

• Log out and log back in to start a new session.
• For a refreshed shell, use newgrp test_group when appropriate.

newgrp test_group

Refreshing the session makes the new membership visible to commands running in that session. It does not change file permissions by itself; the target files or directories must also grant suitable permissions to the group.

Verify the group and its GID

Use getent to look up the group through the system's configured account sources:

getent group test_group

A typical result has this conceptual form:

test_group:x:2000:jowilliams

The fields represent the group name, a group-password placeholder on common systems, the numeric GID, and a comma-separated list of listed supplementary members. The exact output can differ when directory services or other account sources are configured.

You can also look up the numeric ID directly:

getent group 2000

Verify a user's memberships

Check the configured identities and memberships for jowilliams with:

id jowilliams

Look for test_group in the groups portion of the output. The result commonly includes the user's numeric UID, primary group, and supplementary groups.

How the group database represents the group

On systems using local account files, /etc/group is the local group database. A group entry records the group name, its GID, and a list of supplementary members. A conceptual entry looks like:

test_group:x:2000:jowilliams

Do not manually edit /etc/group when standard administration commands are available. Tools such as addgroup, groupadd, adduser, and usermod are designed to update account data consistently and reduce the risk of syntax or locking errors.

Safe administration checklist

• Check whether the group name already exists: getent group test_group.
• Check whether a requested GID is already assigned: getent group 2000.
• Spell existing group and user names exactly, including underscores and capitalization.
• Use sudo only when required and verify the command before executing it.
• Avoid manually editing system account files when supported administration commands are available.
• Plan group changes on multi-user systems because they can change access to files, directories, devices, and shared services.
• After changing membership, start a new login session before testing access from the affected account.

Troubleshooting common problems

“addgroup: command not found”

The distribution may not install the higher-level addgroup utility or may use a different administration package. Use the distribution's documented tool, commonly groupadd, and consult local help for exact options:

sudo groupadd test_group

The group name already exists

Another configured account source may already contain the name. Check it with:

getent group test_group

Reuse the existing group if it is the intended one, or select a distinct name. Do not create a second administrative concept with a confusingly similar name.

GID 2000 is already in use

Find the existing entry:

getent group 2000

Choose an unused GID unless the existing numeric mapping is intentionally required and your account-management system supports the needed operation.

Adding the user fails

The account or group may not exist, the names may be mistyped, or the command may lack administrative privileges. Verify both records:

getent passwd jowilliams
getent group test_group

Then rerun the appropriate command with sudo.

The --gid option is rejected

Option syntax differs between implementations. Read the local help:

addgroup --help

Depending on the distribution, the equivalent may be groupadd -g 2000 test_group.

The user was added but access does not work immediately

The current session may still have its previous group credentials. Log out and back in, or start an appropriate refreshed shell with newgrp test_group. Then inspect the resource itself: its group ownership, permission bits, ACLs, and any parent-directory permissions must allow the required access.

Complete example workflow

The following sequence creates test_group with GID 2000, adds jowilliams, and verifies both records:

getent group test_group
getent group 2000
sudo addgroup --gid 2000 test_group
sudo adduser jowilliams test_group
getent group test_group
id jowilliams

If either initial lookup returns an existing entry, stop and decide whether the existing group or GID is the one you intend to use. If both are available, the creation and membership commands can proceed.

For related administration work, continue with Linux group creation and membership management.