Skip to content

usermod

Changes an existing user: groups, shell, home directory, name, lock and expiry date.

usermod output

Syntax

usermod [OPTION]... USER

Options

Option Description
-aG GROUPS Add the user to additional groups (keep the existing ones)
-G GROUPS Replace all additional groups with this list
-g GROUP Change the primary group
-s SHELL Change the login shell
-d DIR -m Change the home directory and move its contents
-l NEW_NAME Rename the user
-c TEXT Change the full name or description
-L / -U Lock / unlock the password
-e DATE Let the account expire on DATE (YYYY-MM-DD)

Examples

Add a user to a group:

sudo usermod -aG docker alice
groups alice
alice : alice users sudo docker

What -G without -a does:

sudo usermod -G docker alice
groups alice
alice : alice docker

The groups users and sudo are gone. -G alone replaces all additional groups.

Prevent a user from logging in to a shell:

sudo usermod -s /usr/sbin/nologin deploy
getent passwd deploy
deploy:x:1002:1002:Deploy User:/home/deploy:/usr/sbin/nologin

Lock the password of a user:

sudo usermod -L alice
sudo passwd -S alice
alice L 2026-10-26 0 99999 7 -1

The L means locked. Logins with an SSH key still work, see the warning below.

Rename a user and move the home directory:

sudo usermod -l alicia -d /home/alicia -m alice
getent passwd alicia
alicia:x:1001:1001:Alice Example,,,:/home/alicia:/bin/bash

Try to change a user who is logged in:

sudo usermod -l alicia alice
usermod: user alice is currently used by process 2345

Renaming or changing the UID only works when the user has no running processes.

When do I need it?

  • To give a user access to sudo, docker, www-data or a shared group
  • To disable an account temporarily, for example when someone leaves the team
  • To change the shell of service users to /usr/sbin/nologin
  • To rename an account or move its home directory

-L doesn't block SSH keys

usermod -L only locks the password. Logins with an SSH key keep working. To lock an account completely, also use usermod -e 1 (account expired) or usermod -s /usr/sbin/nologin.

-G without -a removes groups

usermod -G docker alice removes alice from all other additional groups, including sudo. If that was your own admin account, you lose sudo. Always write -aG.

useradd · groups · passwd · gpasswd