File and directory ownership steps use chown command.
usermod — quick reference
Identity and IDs
Change the login name, numeric UID, or GECOS comment on an account that already exists.
| When to use | Command |
|---|---|
Rename a login (updates /etc/passwd name; home path is not renamed automatically) |
sudo usermod -l newname oldname |
| Assign a new UID (files outside home keep old ownership until you fix them) | sudo usermod -u 29999 username |
| Allow a duplicate UID when matching NFS or container IDs | sudo usermod -o -u 29999 username |
| Update the GECOS / full-name comment field | sudo usermod -c "Jane Doe,Ops" username |
| Allow usernames the default regex would reject | sudo usermod -b username |
Groups
Primary group (-g) and supplementary groups (-G) behave differently — read the rows before picking a flag.
| When to use | Command |
|---|---|
| Set a new primary group by name or GID | sudo usermod -g GROUP username |
| Replace the entire supplementary group list (drops groups not listed) | sudo usermod -G group1,group2 username |
| Add supplementary groups without removing existing ones | sudo usermod -aG group1,group2 username |
| Remove the user from specific supplementary groups only | sudo usermod -rG group1 username |
Home directory and shell
Point the account at a new home path or login shell. Moving file contents needs -m with -d.
| When to use | Command |
|---|---|
| Change home directory path only (does not move files or create the directory) | sudo usermod -d /opt/app username |
| Change home and move contents from the old directory | sudo usermod -d /opt/app -m username |
| Set or change the login shell | sudo usermod -s /bin/zsh username |
Expiry, password, and lock state
Account expiration and lock flags write to /etc/shadow. Prefer passwd or chage for interactive password changes.
| When to use | Command |
|---|---|
Set account expiration date (YYYY-MM-DD; empty clears expiry) |
sudo usermod -e 2026-12-31 username |
Days after password expiry before the account is disabled (-1 disables the feature) |
sudo usermod -f 14 username |
Lock password login (prepends ! to the hash in shadow) |
sudo usermod -L username |
| Unlock a previously locked account | sudo usermod -U username |
| Set an already-encrypted password hash (rare — scripting only) | sudo usermod -p '$6$…' username |
Alternate root and help
| When to use | Command |
|---|---|
| Operate on user databases under an alternate prefix (containers, image chroots) | sudo usermod -P /mnt/prefix username |
Chroot into CHROOT_DIR before applying changes |
sudo usermod -R /mnt/chroot username |
| Show brief usage | usermod -h |
usermod — command syntax
Synopsis from usermod -h on Ubuntu 25.04:
usermod [options] LOGINusermod updates /etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow. Every example on this page needs sudo or root.
usermod — command examples
Essential Append supplementary groups — keep existing memberships
When you add someone to docker or sudo you usually want to keep their other supplementary groups. Always combine -a with -G; without -a, usermod -G replaces the whole supplementary list.
Create a test user and two groups, then append one group:
sudo groupadd -f usermod_demo_grp
sudo groupadd -f usermod_demo_grp2
sudo useradd -m usermod_demo
sudo usermod -aG usermod_demo_grp usermod_demo
id usermod_demoSample output:
uid=1001(usermod_demo) gid=1001(usermod_demo) groups=1001(usermod_demo),1002(usermod_demo_grp)Append a second group:
sudo usermod -aG usermod_demo_grp2 usermod_demo
id usermod_demoSample output:
uid=1001(usermod_demo) gid=1001(usermod_demo) groups=1001(usermod_demo),1002(usermod_demo_grp),1003(usermod_demo_grp2)Both supplementary groups are present because -a appends instead of replacing.
Clean up:
sudo userdel -r usermod_demo
sudo groupdel usermod_demo_grp usermod_demo_grp2Essential Replace supplementary groups — common mistake
Running usermod -G without -a drops every supplementary group that is not listed. This example shows the surprise admins hit when they forget -a.
sudo groupadd -f usermod_demo_grp
sudo groupadd -f usermod_demo_grp2
sudo useradd -m usermod_demo
sudo usermod -aG usermod_demo_grp,usermod_demo_grp2 usermod_demo
id usermod_demoSample output:
uid=1002(usermod_demo) gid=1002(usermod_demo) groups=1002(usermod_demo),1004(usermod_demo_grp),1005(usermod_demo_grp2)Now replace with only one group:
sudo usermod -G usermod_demo_grp usermod_demo
id usermod_demoSample output:
uid=1002(usermod_demo) gid=1002(usermod_demo) groups=1002(usermod_demo),1004(usermod_demo_grp)usermod_demo_grp2 disappeared from the supplementary list. Use -aG when you mean “add”, not “set”.
Clean up:
sudo userdel -r usermod_demo
sudo groupdel usermod_demo_grp usermod_demo_grp2Common Change primary group
The primary group controls default ownership on new files. Set it with -g when someone's main team changes.
sudo groupadd -f usermod_demo_grp
sudo useradd -m usermod_demo
sudo usermod -g usermod_demo_grp usermod_demo
id usermod_demoSample output:
uid=1003(usermod_demo) gid=1006(usermod_demo_grp) groups=1006(usermod_demo_grp)The primary GID is now usermod_demo_grp instead of a private group matching the username.
Clean up:
sudo userdel -r usermod_demo
sudo groupdel usermod_demo_grpCommon Rename login — verify getent
Renaming with -l updates the login name in /etc/passwd. It does not rename /home/oldname automatically — plan a separate move if you need the home path to match.
sudo useradd -m -c "Demo User" usermod_demo
sudo usermod -l usermod_demo_new usermod_demo
getent passwd usermod_demo_new
getent passwd usermod_demoSample output:
usermod_demo_new:x:1004:1004:Demo User:/home/usermod_demo:/bin/shThe old name returns nothing — the account answers to usermod_demo_new now.
Clean up:
sudo userdel -r usermod_demo_newCommon Move home directory with -d and -m
When you relocate an account, -d alone only changes the path in /etc/passwd. Add -m to create the target (if needed) and copy the contents of the old home.
sudo useradd -m usermod_demo
echo "relocate me" | sudo tee /home/usermod_demo/note.txt >/dev/null
sudo usermod -d /opt/usermod_demo_home -m usermod_demo
ls /opt/usermod_demo_home/
getent passwd usermod_demo | cut -d: -f6Sample output:
note.txt
/opt/usermod_demo_homenote.txt moved with the skel files. Fix ownership if anything still shows the old UID path on disk outside home.
Clean up:
sudo userdel -r usermod_demo
sudo rm -rf /opt/usermod_demo_homeCommon Shell, account expiry, and inactive days
Combine shell changes with expiry metadata for contractors or seasonal accounts.
sudo useradd -m usermod_demo
sudo usermod -s /bin/dash -e 2026-12-31 -f 14 usermod_demo
getent passwd usermod_demo | cut -d: -f6-7
sudo chage -l usermod_demo | egrep 'Expire|Password inactive'Sample output:
/home/usermod_demo:/bin/dash
Account expires : Dec 31, 2026
Password inactive : 14Confirm with chage before relying on expiry in production.
Clean up:
sudo userdel -r usermod_demoAdvanced Lock and unlock password login
-L disables password authentication by prefixing the shadow hash with !. The account may still accept SSH keys. Set a password first if you need a clear before/after hash comparison.
sudo useradd -m usermod_demo
echo 'usermod_demo:TempPass123!' | sudo chpasswd
sudo usermod -L usermod_demo
sudo getent shadow usermod_demo | cut -d: -f1-2
sudo usermod -U usermod_demo
sudo getent shadow usermod_demo | cut -d: -f1-2Sample output:
usermod_demo:!$y$j9T$...
usermod_demo:$y$j9T$...The leading ! while locked prevents password login; it is gone after -U.
Clean up:
sudo userdel -r usermod_demoAdvanced Change UID — check file ownership
Changing UID with -u updates the passwd entry but not existing file ownership elsewhere on disk. Use -o only when you intentionally want duplicate UIDs (NFS, LXC mappings).
sudo useradd -m usermod_demo
sudo usermod -u 29999 usermod_demo
getent passwd usermod_demoSample output:
usermod_demo:x:29999:1009::/home/usermod_demo:/bin/shRun find or chown -R on data directories if the user owned files before the UID change.
Clean up:
sudo userdel -r usermod_demousermod — when to use / when not
| Use usermod when | Use something else when |
|---|---|
| The account already exists and you need to change groups, shell, home, UID, or lock state | You are creating a new login → useradd or adduser |
You want one command to edit /etc/passwd and /etc/shadow fields together |
You only need a friendly interactive password change → passwd username |
You are appending supplementary groups on any distro (-aG) |
You are on Debian/Ubuntu adding one existing user to one existing group → adduser user group may be simpler |
| You must remove the account entirely | userdel / deluser --remove-home |
usermod vs useradd
| usermod | useradd | |
|---|---|---|
| Purpose | Modify existing accounts | Create new accounts |
| Default context | Groups, shell, home, lock | UID/GID allocation, skel copy |
| Group append | -aG (must include -a) |
N/A at create time — use -G on useradd |
| Home migration | -d with optional -m |
-m creates home at account creation |
| Best for | Ongoing account maintenance | First-time account provisioning |
See the useradd for creation flags.
Related commands
| Command | One line |
|---|---|
| groupadd | Create groups before usermod -g or -G |
passwd |
Interactive password changes |
id |
Quick view of UID, GID, and groups |
Browse the full index in our Linux commands reference.
usermod — interview corner
What does usermod do in Linux?
usermod edits an existing row in the local account databases — it does not create users. It can rename the login (-l), change UID (-u), switch primary group (-g), replace or append supplementary groups (-G / -aG), relocate home (-d / -m), change shell (-s), set expiry (-e), and lock or unlock password login (-L / -U).
Files touched include /etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow. Only root or sudo should run it.
A strong answer is:
"usermod modifies existing local users — groups, shell, home, UID, expiry, and lock state — by updating passwd, shadow, and group databases. I use useradd or adduser to create accounts first."
What is the difference between usermod -G and usermod -aG?
-G sets the supplementary group list to exactly what you pass. Any supplementary group you omit is removed. That is a common production mistake when adding someone to docker.
-aG appends to the current supplementary list without dropping existing groups. The -a flag only works together with -G; it has no effect alone.
sudo usermod -aG docker alice # safe append
sudo usermod -G docker alice # replaces entire supplementary listA strong answer is:
"-aG appends supplementary groups; -G alone replaces the whole supplementary list. I always use -aG when adding groups and verify with id."
How do you move a user's home directory with usermod?
-d alone only changes the path stored in /etc/passwd. Files stay in the old directory unless you add -m (move home), which copies the old home contents into the new location and creates the target directory when needed.
After moving, confirm:
getent passwd username | cut -d: -f6
ls -la /new/home/pathLarge trees may need rsync instead of -m for speed or cross-filesystem moves.
A strong answer is:
"I use usermod -d NEW -m user to update passwd and move home contents. For big or cross-mount moves I rsync and chown, then update -d."
How does usermod -L lock an account?
-L locks password authentication by placing ! before the encrypted password field in /etc/shadow. SSH public-key login may still work if it is configured. -U removes the lock prefix.
Accounts without a password hash may warn on unlock — set a password with passwd when you need predictable lock semantics.
A strong answer is:
"-L prefixes the shadow hash with ! so password login fails; -U removes it. Key-based SSH can still work. I verify with getent shadow and test login paths."
When do you use usermod instead of useradd?
useradd (or Debian adduser) provisions a new account — UID, default groups, skel, home. usermod adjusts an account that is already on the system: extra groups, shell changes, renaming, UID maps, or locking leavers.
Typical flow: create with useradd -m, then usermod -aG for role groups, then usermod -L when someone leaves.
A strong answer is:
"useradd creates; usermod maintains — groups, shell, home moves, UID, lock. I create once, then usermod -aG for access changes over time."
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
User lost group memberships after usermod -G |
-G replaces supplementary groups |
Re-add with usermod -aG group user and verify id |
usermod: group 'foo' does not exist |
Group not created | groupadd foo first, or pick an existing GID with -g |
UID 'N' already exists |
Duplicate UID without -o |
Choose a free UID or add -o when duplicates are intentional |
| Home path changed but files missing | Used -d without -m |
Re-run with -m, or copy manually and chown -R |
usermod: directory /path exists on -m |
Target path already present | Remove or pick an empty path, then retry |
cannot lock /etc/passwd |
Another admin tool holds the file | Wait for vipw/adduser to finish; avoid parallel edits |
| Unlock warns about passwordless account | No password hash set | Run passwd username before lock/unlock tests |
usermod: user X is currently used by process |
Active sessions for that login | Log the user out or kill sessions, then retry |
