Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Permissions and Users

Linux usermod command

Reference for the Linux usermod command: add a user to groups with -aG, change shell, home, login name or UID, lock and unlock accounts, and avoid common traps.

usermod changes an existing account: its supplementary groups, login shell, home directory, comment, expiry date or even its login name and UID. It edits the same files as useradd (/etc/passwd, /etc/shadow, /etc/group), so it needs root.

By far the most common use is adding a user to a group, and by far the most common mistake is forgetting the -a flag: usermod -G docker alice replaces all of alice's supplementary groups with docker, quietly removing her from sudo. Always write -aG.

Terminal
sudo usermod -aG docker alice

Try it

Changing accounts needs root, so these examples work on copies of the data and on the group lists the system reports.

Bash Group lists before and after (sample data)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Current groups of this process

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
usermod [OPTION]... LOGIN
Option Description
-aG LIST Append the user to the comma-separated supplementary groups, keeping existing ones. Needs -G.
-G LIST Set the supplementary groups to exactly LIST (replaces them).
-g GROUP Change the primary group.
-s SHELL Change the login shell.
-d DIR [-m] Change the home directory; with -m move the old contents into it.
-l NEWNAME Rename the login (home directory and mail spool are not renamed).
-u UID Change the numeric ID; files in the home directory are re-owned, others are not.
-c TEXT Change the comment (GECOS) field.
-L, -U Lock or unlock the password (puts a ! before the hash in /etc/shadow).
-e DATE Set the account expiry date (YYYY-MM-DD; empty string removes it).

Returns: 0 on success; 6 if the user does not exist, 8 if the user is currently logged in (when renaming or changing the UID), 9 if the new name is taken.

Usage notes

  • Group changes apply at next login. A running shell keeps its old group list. Log out and in, or start newgrp/su - alice, to pick up the new group (see newgrp).
  • -a only works with -G. usermod -a docker alice is an error; the correct form is usermod -aG docker alice.
  • Locking is not total. -L blocks password logins, but SSH keys still work unless the account is also expired or its shell is nologin. Use usermod -e 1 alice to expire it, or set -s /usr/sbin/nologin.
  • Renaming a user. After usermod -l new old you usually also want -d /home/new -m and groupmod -n new old for the private group.
  • Changing a UID leaves stray files. Search with find / -xdev -uid OLD and fix them with chown.
  • Not while the user has processes. Kill or wait for them before renaming or changing the UID, or usermod refuses.
  • Verify with id alice, which reads the files fresh each time.