usermod

What it does

usermod modifies attributes of an existing user account — shell, home directory, username, supplementary group memberships, account lock status, and more — by editing /etc/passwd, /etc/shadow, and /etc/group. Unlike useradd, it operates on an account that already exists.

Beginner examples

• sudo usermod -aG docker alice — add alice to the docker group, keeping her existing groups
• sudo usermod -s /bin/zsh alice — change alice's login shell to zsh
• sudo usermod -L alice — lock the account so it can't log in with a password
• sudo usermod -U alice — unlock it again
• groups alice — check current group memberships before and after a change

sudo usermod -aG sudo alice

Advanced examples

• Rename a user and relocate their home directory in one step: sudo usermod -l bob -d /home/bob -m alice (must be logged out; -m moves the contents of the old home directory to the new path).
• Add a user to several groups at once while preserving existing membership: sudo usermod -aG docker,sudo,www-data alice.
• Change a user's UID (rare, and requires fixing file ownership afterward): sudo usermod -u 2000 alice && find / -user 1500 -exec chown -h 2000 {} \;.
• Lock an account pending investigation without deleting it: sudo usermod -L suspicious_user, reversible later with -U.

sudo usermod -aG docker,sudo alice && groups alice

Common mistakes

• The single most common usermod mistake: running usermod -G docker alice intending to add the docker group, but actually replacing all of alice's supplementary groups with just docker, silently dropping her from sudo or any other group she was in. Always use -aG (append) unless you specifically intend to reset the full group list.
• Expecting a group change to apply to an already-open shell session — it won't until the user logs out and back in (or starts a fresh session with su - user).
• Changing -d without -m and leaving the old home directory's contents behind at the old path while the account now points somewhere empty.
• Renaming a user with -l and forgetting that cron jobs, file ownership by old username-derived paths, or scripts hardcoding the old name may break.

Tips

• Always verify with groups username or id username before and after a -G/-aG change to confirm the result matches your intent.
• Use getent group groupname to confirm a group exists before trying to add a user to it.
• When in doubt about -G vs -aG, default to -aG — it's non-destructive, whereas -G alone requires you to list every group the user should remain in.

Best practices

• Make -aG (append) the default habit for adding group memberships in scripts and runbooks; reserve plain -G for cases where you deliberately want to set an exact, complete group list.
• Script account changes idempotently — check current state with id/groups before modifying, especially in configuration management tools that may run usermod repeatedly.
• Document any UID/username changes and grep for hardcoded old usernames or UIDs in cron, systemd units, and application configs before renaming or renumbering an account.

Real-world use cases

• Granting a new team member access to the docker or sudo group after their account already exists, without disturbing their other group memberships.
• Locking a departing or compromised account immediately (usermod -L) while a full offboarding (userdel) is still pending review.
• Correcting a user's login shell after installing a new shell (e.g. switching from /bin/bash to /usr/bin/zsh).

Common interview questions

• What's the difference between usermod -aG and usermod -G? -aG appends the specified groups to the user's existing memberships; -G alone replaces the entire supplementary group list, removing the user from any group not explicitly listed.
• Why doesn't a new group membership take effect immediately in an open terminal? Group membership is resolved at login/session start, so an already-running shell keeps its old group list until the user logs out and back in or starts a new session.
• How would you safely add a user to a new group without risking their existing access? Use usermod -aG newgroup username — never plain -G, which would silently drop them from any groups not listed.