gpasswd

Administer group members and administrators

Groupsintermediategroupsmembershipadministration

gpasswd [OPTIONS] GROUP

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

On this page

SYNTAX

gpasswd [OPTIONS] GROUP

[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
`-a, --add USER`	Add one user to the named group
`-d, --delete USER`	Remove one user from the named group
`-A, --administrators USER_LIST`	Set the comma-separated list of group administrators
`-M, --members USER_LIST`	Replace the complete comma-separated member list
`-r, --remove-password`	Remove the group password
`-R, --restrict`	Restrict newgrp access to listed group members

Distribution compatibility

Ubuntu
Debian
Fedora
Arch
macOS (not available; use dseditgroup or dscl)

What it does

gpasswd administers a group's members and administrators and can manage the legacy group-password fields. Use -a and -d for one-user membership changes. -A sets the administrator list, while -M replaces the complete explicit member list rather than appending to it.

Group-password workflows are generally obsolete. Explicit membership and modern privilege controls are clearer and safer for most systems.

Beginner examples

sudo gpasswd -a alice developers — add alice to developers.
sudo gpasswd -d alice developers — remove alice from the group.
getent group developers — inspect the resolved group entry afterward.
Ask the user to start a new login session before testing supplementary access.

sudo gpasswd -a alice developers
getent group developers

Advanced examples

sudo gpasswd -A alice developers replaces the group-administrator list with alice. Supply a comma-separated list when more than one administrator is required.
Warning: sudo gpasswd -M alice,bob developers replaces the entire explicit member list. It does not append alice and bob; any omitted explicit members are removed.
For safer multi-member management, inspect getent group developers, calculate the intended complete list, review it, apply -M, and inspect the result again.
sudo gpasswd -r developers removes a group password; -R restricts newgrp access to listed members, though password-based group access is generally obsolete.

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

Using -M as though it meant "add many" and unintentionally removing existing explicit members.
Expecting a newly added supplementary group to appear inside an existing login shell.
Confusing -A administrators with -M ordinary members.
Relying on group passwords instead of explicit, auditable membership.
Editing only local files even though group identity is centrally managed through NSS.

Tips

Use -a and -d for incremental changes; they make intent easier to review.
Run getent group GROUP immediately before and after an administrative change.
Quote or validate generated user lists before passing them to -A or -M.
Check id -nG USER from a fresh session when validating effective membership.

Best practices

Apply least privilege and remove memberships that are no longer required.
Prefer one-user -a and -d changes unless replacing the full list is intentional.
Treat -M as a destructive replacement: inventory, review, apply, and verify.
Keep group administrator lists small, documented, and periodically reviewed.
Use managed identity systems where appropriate instead of legacy group passwords.

Real-world use cases

Granting a developer access to a shared project directory.
Removing a departing team member without recreating the group.
Delegating membership administration for a project group.
Reconciling an explicit member list from an approved access record.
Restricting legacy newgrp behavior while older systems are being modernized.

Common interview questions

What is the difference between -a and -M? -a adds one member; -M replaces the complete explicit member list.
Why might membership not appear immediately? Supplementary group lists are often initialized at login, so an existing session can remain stale.
What does -A manage? The comma-separated list of group administrators, not the ordinary member list.
Are group passwords recommended? Generally no. Explicit account membership is easier to audit and aligns better with modern access management.

Frequently Asked Questions

When does a newly added membership become visible?

Supplementary groups are commonly established at login, so the user often needs a new login session.

Does gpasswd -M append users?

No. It replaces the complete explicit member list, so omitted members are removed from that list.

What does gpasswd -A do?

It replaces the comma-separated list of group administrators, who can manage membership according to local policy.

Should I use group passwords?

Group-password workflows are generally obsolete and are usually less suitable than explicit, administrator-managed membership.

Is gpasswd available on macOS?

No. Use macOS tools such as dseditgroup or dscl.

Cheat sheet

Download a quick-reference cheat sheet for gpasswd.