cheatsheet

groupadd Command in Linux: Syntax, Options & Practical Examples

groupadd creates a new entry in /etc/group and /etc/gshadow. Use it to add project teams, service groups, or fixed GIDs before assigning users with usermod or adduser.

Published

Updated

Read time 8 min read

Reviewed byDeepak Prasad

groupadd Command in Linux: Syntax, Options & Practical Examples
About groupadd creates a new entry in /etc/group and /etc/gshadow. Use it to add project teams, service groups, or fixed GIDs before assigning users with usermod or adduser.
Tested on Ubuntu 25.04 (Plucky Puffin); groupadd (passwd 1:4.16.0-7ubuntu1); kernel 7.0.0-27-generic
Package passwd (apt/deb) · shadow-utils (dnf/rpm)
Man page groupadd(8)
Privilege root / sudo
Distros

All major Linux distros that ship shadow-utils / passwd (RHEL, AlmaLinux, Fedora, Ubuntu, Debian, SUSE, Arch, and others).

Ubuntu and Debian: addgroup (friendly wrapper in the adduser package).
Related guide

groupadd — quick reference

Basic group creation

Create a named group when you need a shared GID before adding members.

When to use Command
Create a group with the next free GID from /etc/login.defs sudo groupadd developers
Exit successfully when the group already exists (scripts) sudo groupadd -f developers
Show built-in usage text groupadd --help

GID control

Pick a numeric group ID when IDs must match across hosts or match NFS exports.

When to use Command
Create a group with a specific GID sudo groupadd -g 5100 developers
Allow a duplicate GID (legacy or special layouts) sudo groupadd -o -g 5100 devteam
Override GID pool for this run only sudo groupadd -K GID_MIN=5200 -K GID_MAX=5299 project

System groups

Low-GID groups for daemons and services — IDs come from the system range in /etc/login.defs.

When to use Command
Create a system group (low GID range) sudo groupadd -r appgroup
Same as above with long option sudo groupadd --system appgroup

groupadd — command syntax

Synopsis from groupadd --help on Ubuntu 25.04 (passwd 1:4.16.0-7ubuntu1):

text 
Usage: groupadd [options] GROUP

Options:
  -f, --force                   exit successfully if the group already exists,
                                and cancel -g if the GID is already used
  -g, --gid GID                 use GID for the new group
  -K, --key KEY=VALUE           override /etc/login.defs defaults
  -o, --non-unique              allow to create groups with duplicate
                                (non-unique) GID
  -r, --system                  create a system account

groupadd writes to /etc/group and /etc/gshadow. Most examples need sudo.

groupadd — command examples

Essential Create a group and verify with getent

Create a normal project group. Linux picks the next available GID from the configured range.

Run the command:

bash 
sudo groupadd devteam

Sample output (no lines on success — that is normal):

Confirm the group exists in the group database:

bash 
getent group devteam

Sample output:

text 
devteam:x:1007:

The fields are groupname:password_placeholder:GID:member_list. An empty member list means no users are in the group yet — add them with usermod or adduser.

Essential Assign a fixed GID for cross-host consistency

Use a specific GID when the same numeric ID must exist on every server — common with NFS or configuration management.

Run the command:

bash 
sudo groupadd -g 5100 developers

Check the assigned GID:

bash 
getent group developers

Sample output:

text 
developers:x:5100:

Before reusing a GID, confirm it is free with getent group 5100 or getent group | awk -F: '$3==5100'.

Essential Create a low-GID system group for a service

Service accounts often need a dedicated group in the system GID range (typically below 1000 on Ubuntu).

Run the command:

bash 
sudo groupadd -r svcgrp

Verify the GID landed in the system range:

bash 
getent group svcgrp

Sample output:

text 
svcgrp:x:980:

Pair this group with a system user via useradd -r -g svcgrp or adduser --system --ingroup svcgrp.

Common Use -f so scripts do not fail when the group exists

In automation, the same groupadd line may run more than once. -f treats an existing group as success instead of an error.

Create the group once, then rerun with -f:

bash 
sudo groupadd devteam
sudo groupadd devteam 2>&1 || true
sudo groupadd -f devteam
echo "exit code: $?"

Sample output:

text 
groupadd: group 'devteam' already exists
exit code: 0

Without -f, the second groupadd fails. With -f, the same command exits 0 and prints nothing on success. Remove test groups with sudo groupdel devteam.

Common GID already exists — error and fix

A common mistake is reusing a GID that another group already owns.

Try to create a second group with the same GID (without -o):

bash 
sudo groupadd -g 5100 developers
sudo groupadd -g 5100 analysts

Sample output:

text 
groupadd: GID '5100' already exists

Pick a free GID, or use -o only when duplicate GIDs are intentional (see the advanced example below).

Common Override GID_MIN and GID_MAX for one run

-K passes temporary overrides to /etc/login.defs rules — useful when a project needs IDs in a dedicated band.

Run the command:

bash 
sudo groupadd -K GID_MIN=5200 -K GID_MAX=5299 projecta

Verify the GID fell inside the band:

bash 
getent group projecta

Sample output:

text 
projecta:x:5200:

These -K values apply only to this invocation; they do not edit /etc/login.defs on disk.

Advanced Allow duplicate GID with -o (unusual layouts)

Normally every group has a unique GID. -o relaxes that rule — rare outside legacy migrations.

Create two groups sharing one GID:

bash 
sudo groupadd -g 5100 sharedgid
sudo groupadd -o -g 5100 sharedgid2
getent group | grep ':5100:'

Sample output:

text 
sharedgid:x:5100:
sharedgid2:x:5100:

Duplicate GIDs confuse permission checks on many tools — prefer unique GIDs unless you have a documented reason.

Advanced Permission denied without root or sudo

groupadd modifies system databases and refuses to run as a normal user.

Run without elevated privileges:

bash 
groupadd testgrp

Sample output:

text 
groupadd: Permission denied.

Prefix with sudo or run as root. Clean up test groups with sudo groupdel GROUP.

groupadd — when to use / when not

Use groupadd when Use something else when
  • You need a new group record before adding members with usermod -aG or adduser user group
  • You are scripting on RHEL, Fedora, Ubuntu, Debian, or any distro with shadow-utils
  • You must assign a fixed or system GID at creation time
  • You want a portable, low-level command that behaves the same across distros
  • You are on Ubuntu or Debian and prefer guided output → addgroup via the adduser package
  • The group already exists and you need to rename it or change its GID → groupmod
  • You only need to add an existing user to an existing group → usermod or adduser user group
  • You want to remove a group → groupdel
  • Groups come from LDAP or Active Directory — not local /etc/group

groupadd vs addgroup

groupadd addgroup (Debian/Ubuntu)
Availability shadow-utils on most distros adduser package on Debian family
Interface Low-level, script-friendly Wrapper with Debian policy defaults
GID flags -g, -r, -K, -o --gid, --system, --firstgid, …
Best for Portable automation Hands-on admin on Ubuntu/Debian

On Debian and Ubuntu, sudo addgroup NAME ultimately calls the same databases — see the adduser command for the wrapper syntax.

Nearby tools for the same workflow — create groups, attach users, and clean up.

Command One line
groupadd Create groups (this page)
useradd Portable user creation with -g / -G
chage Password aging (users, not groups)

Browse the full index in our Linux commands reference.

groupadd — interview corner

What does groupadd do in Linux?

groupadd adds a new row to /etc/group (and related shadow data in /etc/gshadow). Every file and process on Linux has a user and group owner; supplementary groups control shared access.

When you run:

bash 
sudo groupadd devteam
getent group devteam

Sample line:

text 
devteam:x:1007:

The third field is the GID programs use in ls -l group columns and in permission checks.

A strong answer is:

"groupadd creates a local group with a name and GID in /etc/group. I verify with getent group, then add members using usermod -aG or adduser user group."

What is the difference between a GID and a UID?

A UID identifies a user account; a GID identifies a group. Files store both — owner UID and owning group GID — in inode metadata.

bash 
ls -l /etc/passwd

Sample output:

text 
-rw-r--r-- 1 root root 2841 Jul  1 12:00 /etc/passwd

Here root appears twice: the user (UID 0) and the owning group (GID 0). groupadd only creates group records; user accounts are separate (useradd, adduser).

A strong answer is:

"UID is for users, GID is for groups. groupadd allocates a GID; users reference it through their primary or supplementary group lists."

When would you create a system group with -r?

System groups live in the low GID range reserved for OS services — see SYS_GID_MIN / SYS_GID_MAX in /etc/login.defs. Daemons often run as a dedicated user whose primary group is also dedicated.

bash 
sudo groupadd -r nginx
getent group nginx

Sample output:

text 
nginx:x:980:

Use -r when the group is for a service account, not a human team.

A strong answer is:

"I use groupadd -r for daemon and service groups so the GID comes from the system range defined in login.defs, keeping human project groups in the higher band."

Should you use groupadd or addgroup on Ubuntu?

addgroup on Ubuntu is a Perl wrapper from the adduser package — friendlier messages and Debian policy defaults. groupadd is the portable shadow-utils binary underneath.

For scripts that must run on RHEL and Ubuntu, use groupadd. For interactive work on Debian family systems, addgroup is fine.

A strong answer is:

"On Ubuntu I might use addgroup interactively, but in playbooks and portable scripts I use groupadd because shadow-utils behaves consistently everywhere."

What does groupadd -f do?

-f means do not fail if the group already exists. If you also pass -g and that GID is taken, -f cancels the GID request but still exits successfully — read the man page before relying on that in scripts.

bash 
sudo groupadd ops
sudo groupadd -f ops
echo $?

Sample output:

text 
0

A strong answer is:

"groupadd -f is for idempotent automation — rerunning the same create line does not break the script when the group is already there."

Troubleshooting

Symptom Likely cause Fix
group 'NAME' already exists Duplicate group name Use the existing group, pick another name, or groupadd -f in scripts
GID 'N' already exists GID taken by another group getent group N; choose a free GID or use -o only if duplicates are intentional
Permission denied Not root Run with sudo
invalid group name Name fails NAME_REGEX from login.defs Use lowercase alphanumeric names; check man groupadd
Group missing after reboot on LDAP systems Local group vs directory Confirm with getent group — NSS may be served by SSSD/LDAP
Rohan Timalsina

is a technical writer and Linux enthusiast who writes practical guides on Linux commands and system administration. He focuses on simplifying complex topics through clear explanations.