usermod Cheatsheet
Quick reference for modifying Linux user accounts with usermod and managing groups with groupadd, gpasswd, and groupdel
The usermod command changes existing user accounts in Linux, from group membership and login shell to home directory, UID, and account locking. This cheatsheet also covers the group commands you use alongside it.
Basic Syntax
Core usermod command forms.
| Command | Description |
|---|---|
sudo usermod [options] username | General syntax |
sudo usermod -c "Full Name" username | Change the GECOS/comment field |
id username | Show UID, GID, and group membership |
getent passwd username | Show the user’s account entry |
usermod --help | List all available options |
Supplementary Groups
Add or remove secondary group membership.
| Command | Description |
|---|---|
sudo usermod -aG docker username | Add user to one group |
sudo usermod -aG docker,sudo username | Add user to multiple groups |
sudo usermod -G docker username | Replace all supplementary groups with docker |
sudo usermod -rG docker username | Remove user from one group |
sudo gpasswd -d username docker | Remove user from one group (alternative) |
Primary Group
Change the group assigned to new files the user creates.
| Command | Description |
|---|---|
sudo usermod -g developers username | Set primary group to developers |
id -gn username | Show the user’s primary group |
newgrp developers | Start a shell with developers as the active group |
sudo chgrp developers file | Change group ownership of a file |
sudo chgrp -R developers dir/ | Change group ownership recursively |
Home Directory and Shell
Move the home directory or change the login shell.
| Command | Description |
|---|---|
sudo usermod -d /srv/username -m username | Change home path and move its contents |
sudo usermod -d /srv/username username | Change home path only (old files stay in place) |
sudo usermod -s /bin/zsh username | Change login shell |
sudo usermod -s /usr/sbin/nologin username | Disable interactive login |
cat /etc/shells | List valid login shells |
Rename and UID
Change the login name or numeric user ID. Record the old UID before using -u, and review the find results before running chown.
| Command | Description |
|---|---|
sudo usermod -l newname oldname | Rename the user account |
sudo usermod -l newname -d /home/newname -m oldname | Rename user and move home directory |
sudo groupmod -n newname oldname | Rename the matching user private group |
old_uid=$(id -u username) | Record the current UID before changing it |
sudo usermod -u 1050 username | Change UID (files in home are updated) |
sudo find /srv -xdev -uid "$old_uid" -print | Preview files still owned by the old UID under /srv |
sudo find /srv -xdev -uid "$old_uid" -exec chown -h username {} + | Reassign old-UID files under /srv to the user |
Replace /srv with the directory or mount point you need to repair. The -xdev option stays on that filesystem, so scan other mounts separately. Use the same shell session so $old_uid remains available.
Lock, Unlock, and Expiry
Lock or unlock password authentication and set an account expiry date.
| Command | Description |
|---|---|
sudo usermod -L username | Lock the account password |
sudo usermod -U username | Unlock the account password |
sudo usermod -e 2026-12-31 username | Expire the account on a date |
sudo usermod -e "" username | Remove the expiry date |
sudo chage -l username | Show expiry and password aging details |
The -L option blocks password authentication only; SSH keys may still work. The -U option does not remove an account expiry date; use -e "" separately when needed.
Manage Groups
Create, rename, and delete groups.
| Command | Description |
|---|---|
sudo groupadd developers | Create a group |
sudo groupadd -g 1500 developers | Create a group with a specific GID |
sudo groupadd -r appgroup | Create a system group |
sudo groupmod -n devs developers | Rename a group |
sudo groupdel developers | Delete a group |
List Users and Groups
Check who belongs where.
| Command | Description |
|---|---|
groups username | List groups a user belongs to |
getent group developers | Show a group entry and explicitly listed members |
getent group | List all groups |
getent passwd | List all user accounts |
cut -d: -f1 /etc/group | List local group names only |
Primary group membership is recorded in the passwd database, so primary members may be absent from getent group output. Use id username to check a user’s primary and supplementary groups.
Troubleshooting
Quick checks for common usermod problems.
| Issue | Check |
|---|---|
user username is currently used by process | Log the user out and stop their processes before -l, -u, or -d |
| New group not active | Log out and back in, or run newgrp groupname |
| User lost other groups | -G without -a replaces the list; re-add the missing groups with -aG |
group 'name' does not exist | Create it first with groupadd |
unlocking the user's password would result in a passwordless account | Set a password with passwd instead of using -U |
Related Guides
Use these guides for full user and group management tasks.
| Guide | Description |
|---|---|
| usermod Command in Linux | Full usermod tutorial with examples |
| How to Add a User to a Group in Linux | Manage supplementary and primary groups |
| How to Create Groups in Linux | Create groups with groupadd |
| groupdel Command in Linux: Delete a Group | Remove groups with groupdel |
| How to List Groups in Linux | Show group membership |
| useradd Cheatsheet | Create new user accounts |