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.
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.
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.
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
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 (seenewgrp). -aonly works with-G.usermod -a docker aliceis an error; the correct form isusermod -aG docker alice.- Locking is not total.
-Lblocks password logins, but SSH keys still work unless the account is also expired or its shell isnologin. Useusermod -e 1 aliceto expire it, or set-s /usr/sbin/nologin. - Renaming a user. After
usermod -l new oldyou usually also want-d /home/new -mandgroupmod -n new oldfor the private group. - Changing a UID leaves stray files. Search with
find / -xdev -uid OLDand fix them withchown. - Not while the user has processes. Kill or wait for them before renaming or changing the UID, or
usermodrefuses. - Verify with
idalice, which reads the files fresh each time.
Related
useradd,userdel,groupadd,groups,passwd- Lessons: Users and permissions, Permissions