Linux Labs
Where to start First steps track · 15 stages
Linux Labs
EN

usermod — change an account and its groups

6 min Ubuntu 24.04 · shadow 4.13

The usermod command changes an existing account — groups, login shell, home directory, name and locking.

Cheat sheet

10 commands Printable version
  • sudo usermod -aG adm alice add a user to a group, keep others
  • sudo usermod -rG adm alice remove from a group (or gpasswd -d)
  • sudo usermod -G adm,www-data alice set the whole group list anew
  • sudo usermod -g devs alice change the primary group
  • sudo usermod -s /bin/bash alice login shell
  • sudo usermod -s /usr/sbin/nologin svc forbid login
  • sudo usermod -L alice lock the password; -U unlocks
  • sudo usermod -e 2026-12-31 alice the date the account expires
  • sudo usermod -d /home/al -m alice move the home directory
  • id alice check the result

Overview

usermod edits an existing user's entry in /etc/passwd, /etc/shadow and /etc/group. It runs as root and prints nothing on success — check the result with id or getent passwd.

Most often it's used for groups. A user has one primary group (in /etc/passwd) and a list of supplementary ones (in /etc/group). -G sets the whole supplementary list; -a turns the replacement into an addition:

text 
student@ubuntu:~$ id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice),4(adm)
student@ubuntu:~$ sudo usermod -G www-data alice
student@ubuntu:~$ id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice),33(www-data)

Without -a, alice lost adm, and usermod gave no warning. To add one group, use usermod -aG only.

Removing one group is easier with gpasswd -d. Their arguments go in opposite order: usermod -aG group user, but gpasswd -d user group.

Options

10

Full list — man usermod. gpasswd options: -a add, -d remove, -M set the group's member list.

Option What it does Example
-aG groups Add to supplementary groups, keeping the others. sudo usermod -aG adm alice
-G --groups groups Set the whole supplementary group list — without -a the old ones are lost. dangerous sudo usermod -G adm,www-data alice
-g --gid group Change the primary group. sudo usermod -g devs alice
-s --shell shell Change the login shell (nologin forbids login). sudo usermod -s /usr/sbin/nologin svc
-L --lock Lock the password; SSH key login still works. sudo usermod -L alice
-U --unlock Unlock the password. sudo usermod -U alice
-e --expiredate YYYY-MM-DD Account expiry date; an empty string removes it. sudo usermod -e 2026-12-31 alice
-rG groups Remove from the listed supplementary groups only. sudo usermod -rG www-data alice
-d --home dir A new home directory; with -m move the contents there. sudo usermod -d /home/al -m alice
-l --login name Rename the account (the group and directory are separate). sudo usermod -l al alice

Nothing found. Try a shorter query.

Recipes

4

Add to a group and check that nothing was lost

bash 
id -nG alice                       # groups before
sudo usermod -aG www-data alice
id -nG alice                       # after: the old ones plus www-data

Remove from one group

text 
student@ubuntu:~$ sudo gpasswd -d alice www-data
Removing user alice from group www-data

The same without gpasswd: sudo usermod -rG www-data alice.

A new group doesn't work in an open session

A process gets its groups when it starts. An open shell and running services keep the old list:

bash 
sudo -u alice id -nG        # a new process — the new list
sudo systemctl restart app  # the service sees it after a restart

The user themselves needs to log out and back in.

Close login for a while

bash 
sudo usermod -L alice                     # the password no longer works
sudo usermod -s /usr/sbin/nologin alice   # and there's no shell
sudo usermod -e 1 alice                   # or the account has expired

-L closes only password login: an SSH key keeps working. To reopen — -U, the old shell, -e ''.

Troubleshooting

5

usermod: user alice is currently used by process 1234

The name, UID or home directory can't change while the user is logged in. End their sessions (sudo pkill -u alice, see kill) and repeat.

usermod: group 'devs' does not exist

A group given to -g or -G must exist. Create it: sudo groupadd devs.

Added to a group, still no access

The session and services hold the old group list. Check with a new process (sudo -u alice id -nG), log in again, or restart the service.

Groups vanished after usermod -G

That's -G without -a: the list was replaced. Restore the needed ones in one command — sudo usermod -aG sudo,adm alice — and compare with getent group.

gpasswd: user 'alice' is not a member of 'docker'

The user was never in that group — check id -nG alice. If it's the primary group, gpasswd -d won't remove it: the primary group is changed with usermod -g.

Danger zone

2

usermod -G without -a

It replaces all supplementary groups. Granting one permission silently takes away the others — sudo included, and the user loses admin rights.

Changing the UID and the name

usermod -u re-owns only the files in the home directory. Files elsewhere keep the old number — find them with sudo find / -xdev -uid old_UID. usermod -l changes only the name: the group and home directory stay as they were.

See also

  • users-groups — users, groups and where they're stored.
  • useradd — create a user with the right groups from the start.
  • passwd — password locking and status.
  • chage — password and account ages.
  • nologin — the shell that forbids login.
  • permissions — how a group grants access to files.

Found an inaccuracy? Report an error in the article

Practice on this topic

Lessons on this topic

Topics
Loading…