gpasswd is the tool for adding or removing a local user from a group, replacing a group's whole member list, or handing out group administrators. This guide uses the gpasswd shipped by the Ubuntu passwd package, version 1:4.13+dfsg1-4ubuntu3.2, whose local manual identifies the implementation as shadow-utils 4.13.
Allow about 5 minutes for a membership change and its checks. You need the group and user names, a shell account with sudo for most changes, and a plan for undoing the change. The command edits local /etc/group and /etc/gshadow; it does not update NIS or LDAP.
Check that the group and user are the ones you actually intend to change:
getent group PROJECT_GROUP
id USER_NAMEReplace PROJECT_GROUP and USER_NAME with real values. An empty result from getent group means the group is not visible through the system's configured name service. Do not create a new group as a side effect of guessing: stop and confirm the name first.
The local manual says that gpasswd operates on /etc/group and /etc/gshadow. That boundary matters on machines using a directory service. A successful local command is not evidence that an LDAP or NIS group changed.
Add the user with sudo gpasswd --add:
sudo gpasswd --add USER_NAME PROJECT_GROUPShort form: sudo gpasswd -a USER_NAME PROJECT_GROUP. The command changes the named group's member list. It does not start a new login session with the new supplementary group, so the user should log out and back in, or start a fresh session, before testing access.
Checkpoint: ask the name service for the group again.
getent group PROJECT_GROUPThe user's name should appear in the member field. For a more direct view in a fresh session, run id USER_NAME. If the name is absent, check the exact group spelling and whether the group is managed remotely.
Record the current membership, then remove one user with sudo gpasswd --delete:
getent group PROJECT_GROUP
sudo gpasswd --delete USER_NAME PROJECT_GROUP
getent group PROJECT_GROUPShort form: sudo gpasswd -d USER_NAME PROJECT_GROUP. Removing a user can interrupt access to files, sockets or services that rely on the group. It does not necessarily terminate processes that already hold the old supplementary group list, so check both the user's new sessions and any long-running service when access must stop promptly.
To undo this particular change, add the same user again:
sudo gpasswd --add USER_NAME PROJECT_GROUPThat restores membership, not any application state that changed while access was absent.
Use --members when the desired list is known and complete. This is a replacement operation, not an addition:
getent group PROJECT_GROUP
sudo gpasswd --members ALICE,BOB PROJECT_GROUP
getent group PROJECT_GROUPThe comma-separated argument becomes the group's member list. Omitting somebody from the command removes them, so copy the existing list first and review the proposed list before pressing Enter. To make the group have no listed members, the argument must be empty, which is easy to misread and risky to automate. Prefer an explicit review and a tested backup or change record.
There is no general one-command undo for a replacement. Re-run --members with the previously recorded complete list:
sudo gpasswd --members PREVIOUS_USER_1,PREVIOUS_USER_2 PROJECT_GROUPSystem administrators can use --administrators to set who administers the group. The list is also a replacement, so the same omission warning applies:
sudo gpasswd --administrators GROUP_ADMIN_1,GROUP_ADMIN_2 PROJECT_GROUPWarning: group administrators can administer membership and the group password according to the command's normal permission checks. Treat this as a privilege change. Record the old administrator list before editing it, and verify the result with the account and access checks your organisation uses. Keep the argument to one option: the local manual says options cannot be combined, except for --administrators and --members.
Running gpasswd PROJECT_GROUP as an eligible group administrator prompts for a new group password. A group password lets non-members use newgrp to join the group when they know the password. Existing members can use newgrp without it.
Shared passwords are difficult to attribute and easy to spread. Prefer named membership and administrators where possible. If a group password already exists, these commands change its access rules:
sudo gpasswd --restrict PROJECT_GROUP
sudo gpasswd --remove-password PROJECT_GROUP--restrict sets the group password to !. The manual describes this as allowing only members with a password to use newgrp, while --remove-password empties the group password and allows only group members to use newgrp. These are security-sensitive changes. Confirm the intended policy with the people who use the group, then test with a controlled account.
Security warning: use getent group PROJECT_GROUP for membership. Do not read /etc/gshadow into chat, tickets or shell history: it is the secure group database and contains password data.
gpasswd does not change NIS or LDAP groups. Use the corresponding directory-service administration tool.gpasswd -ad USER_NAME PROJECT_GROUP. The manual permits combining only -A and -M; use one membership operation at a time.--members and --administrators replace lists. Preserve the old list before changing it.ENCRYPT_METHOD in /etc/login.defs. Those settings affect group passwords, not ordinary user-password generation through PAM.getent group PROJECT_GROUP shows the intended membership.