groupmod

Change a group's name or numeric ID

Groupsintermediategroupsgidadministration

groupmod [OPTIONS] GROUP_NAME

By CMD Script Team · 3 min read · Last updated July 16, 2026

On this page

SYNTAX

groupmod [OPTIONS] GROUP_NAME

[X]: Optional — the command works without it
X...: Repeatable — you can pass more than one
ALLCAPS: A placeholder — replace it with your own value

Options

Command options and flags
Flag	Description
`-n, --new-name NEW_GROUP`	Rename the group
`-g, --gid GID`	Change the group's numeric group ID
`-o, --non-unique`	Allow a non-unique GID when used with --gid
`-R, --root CHROOT_DIR`	Apply changes inside the specified chroot directory

Distribution compatibility

Ubuntu
Debian
Fedora
Arch
macOS (not available; use dscl for local groups)

What it does

groupmod changes an existing group's name or numeric group ID (GID). Renaming a group preserves its GID, so files owned by that number continue to resolve to the renamed group and file access is preserved.

Changing the GID is different: it updates the account entry but does not automatically rewrite existing files that carry the old numeric GID. Those files need a deliberate ownership migration.

Beginner examples

sudo groupmod -n platform developers — rename developers to platform.
getent group platform — verify the renamed entry and its GID.
sudo groupmod -g 3000 platform — assign the group GID 3000.
Run getent group platform again to verify the final account record.

sudo groupmod -n platform developers
getent group platform

Advanced examples

Record the old GID before changing it, then migrate files that still carry that number:

old_gid=$(getent group platform | cut -d: -f3)
sudo groupmod -g 3000 platform
find / -gid "$old_gid" -exec chgrp -h platform {} +

The explicit form requested in a runbook may use a placeholder: find / -gid OLD_GID -exec chgrp -h platform {} +.

sudo groupmod -R /mnt/rescue -n platform developers changes an entry inside a chroot tree when supported.
Avoid -o unless duplicate GIDs are deliberate, reviewed, and documented; two names resolving to the same number make ownership interpretation ambiguous.

Try it yourself

A simulated shell with a sample home directory — experiment freely, nothing leaves your browser. Type help to list supported commands.

Common mistakes

Assuming a GID change rewrites existing file metadata. It changes the group database, not every filesystem.
Running the ownership migration without first saving the old GID.
Using -o merely to bypass a collision instead of choosing a unique number.
Forgetting shared, removable, or network-mounted filesystems during the old-GID audit.
Treating a rename like a GID change even though a rename preserves numeric ownership.

Tips

Capture getent group GROUP before and after a change for verification and rollback.
Limit find to known filesystems and handle mounts according to your maintenance plan.
Use chgrp -h when the group of symbolic links themselves must be changed.
Coordinate GID changes across hosts that share storage or container volume mappings.

Best practices

Prefer a rename when only the label is wrong; preserving the GID minimizes disruption.
Schedule GID changes with an explicit audit, migration, verification, and rollback plan.
Record both old and new GIDs before making the change.
Keep GIDs unique. Use -o only for a deliberate, documented identity design.
Verify account resolution and representative file access after the migration.

Real-world use cases

Renaming a team from developers to platform without changing file ownership.
Aligning a local group's GID with the value used on shared NFS storage.
Correcting an image or chroot account database before deployment.
Migrating a service group into an organization-wide numeric-ID convention.

Common interview questions

Why does renaming preserve access? Files store a numeric GID, and -n leaves that number unchanged while changing the name that resolves to it.
What happens to files after groupmod -g? They keep the old GID until explicitly migrated.
Why is -o risky? Duplicate GIDs allow multiple names to represent the same numeric owner, which can confuse audits and access decisions.
How do you verify the change? Check getent group platform, audit relevant files by numeric GID, and test representative access.

Frequently Asked Questions

Does renaming a group break file access?

Normally no. A rename preserves the numeric GID, and filesystem ownership is stored by that number.

Does changing a group's GID update existing files?

No. Existing files retain the old numeric GID and must be found and migrated deliberately.

When should I use --non-unique?

Only when duplicate GIDs are an intentional, documented part of the identity design; otherwise they create ambiguous ownership.

Is groupmod available on macOS?

No. Use macOS Directory Service tooling such as dscl for local groups.

Cheat sheet

Download a quick-reference cheat sheet for groupmod.