USERDEL(8)

📦
version 4.20.0.arch1 · 19 versions
, in arch rolling

💖 USERDEL(8) — System Management Commands 💖

okay bestie, welcome to USERDEL, section 8 of the System Management Commands girlies. this is the one that says bye-bye to a user account. let's get into it 🎀

✨ NAME ✨

userdel — delete a user account and related files. that's it, that's the whole job. she's a deleter. 💅

✨ SYNOPSIS ✨

userdel [options] LOGIN

✨ DESCRIPTION ✨

so like, userdel goes into your system account files and yeets every single entry that refers to the user name LOGIN. all of them. gone. 💀

one tiny catch tho — the user you're naming has to actually exist first. you can't delete a ghost, bestie. 👻

✨ OPTIONS ✨

here's everything she takes. every single one, no skips:

  • -f, --force — forces the removal of the user account and any other requested actions, straight up skipping all the safety checks. she does not ask, she does not warn, she just goes.
⚠️ note: this option is dangerous and may leave your system in an inconsistent state. like, genuinely. this is not a drill. 🚨
  • -h, --help — shows you the help message and dips out. the classic. 🫶
  • -r, --remove — this one is the real cleanup queen. files in the user's home directory get removed along with the home directory itself, AND the user's mail spool. but heads up bestie — files chilling in other file systems? you're gonna have to go search for those and delete them manually. she's not chasing those down for you. 🧹

the mail spool is defined by the MAIL_DIR variable in the login.defs file. iykyk.

  • -R, --root CHROOT_DIR — applies changes in the CHROOT_DIR directory and pulls the configuration files from the CHROOT_DIR directory too. only absolute paths are supported here. and nope, no SELINUX support. 🙈
  • -P, --prefix PREFIX_DIR — applies changes in the PREFIX_DIR directory and uses the config files from the PREFIX_DIR directory. important: this one does not chroot, and it's intended for preparing a cross-compilation target. some limitations, bestie: NIS and LDAP users/groups are not verified, PAM authentication uses the host files, and there's no SELINUX support. 🌸
  • -Z, --selinux-user — removes any SELinux user mapping for the user's login. bye mapping 💅

✨ CONFIGURATION ✨

these are the config variables in /etc/login.defs that change how this tool behaves. the lore, if you will:

MAIL_DIR (string)

the mail spool directory. this is needed to manipulate the mailbox when its corresponding user account is modified or deleted. if it's not specified, a compile-time default is used. also, the parameter CREATE_MAIL_SPOOL in /etc/default/useradd decides whether the mail spool should be created in the first place. 🍓

MAIL_FILE (string)

defines where the user's mail spool files live, relative to their home directory.

and fyi: the MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and userdel to create, move, or delete the user's mail spool. shared custody. 🤝

MAX_MEMBERS_PER_GROUP (number)

maximum members per group entry. when the max is reached, a new group entry (line) gets started in /etc/group — with the same name, same password, and same GID. iconic, honestly.

the default value is 0, meaning there are no limits on the number of members in a group.

this feature (split group) lets you limit how long the lines in the group file can get. super useful for making sure lines for NIS groups don't blow past 1024 characters.

if you genuinely need to enforce that limit, you can use 25.

⚠️ note: split groups may not be supported by all tools (even inside the Shadow toolsuite). you should not use this variable unless you really need it. fr fr.

USERDEL_CMD (string)

if it's defined, this command runs when removing a user. it should remove any at/cron/print jobs etc. owned by the user being removed — and the user gets passed in as the first argument. 🫶

the return code of the script is not taken into account. she simply does not care.

here's an example script that removes the user's cron, at and print jobs:

#! /bin/sh

# Check for the required argument.
if [ $# != 1 ]; then
     echo "Usage: $0 username"
     exit 1
fi

# Remove cron jobs.
crontab -r -u $1

# Remove at jobs.
# Note that it will remove any jobs owned by the same UID,
# even if it was shared by a different username.
AT_SPOOL_DIR=/var/spool/cron/atjobs
find $AT_SPOOL_DIR -name "[^.]*" -type f -user $1 -delete \;

# Remove print jobs.
lprm $1

# All done.
exit 0

USERGROUPS_ENAB (boolean)

if it's set to yes, userdel will remove the user's group if it contains no more members, and useradd will create by default a group with the name of the user. the little duo doing their thing ✨

✨ FILES ✨

the whole roster of files she touches:

  • /etc/group — group account information.
  • /etc/login.defs — shadow password suite configuration.
  • /etc/passwd — user account information.
  • /etc/shadow — secure user account information.
  • /etc/shadow-maint/userdel-pre.d/*, /etc/shadow-maint/userdel-post.d/* — run-part files to execute during user deletion. the environment variable ACTION will be populated with userdel and SUBJECT with the username. userdel-pre.d will be executed prior to any user deletion. userdel-post.d will execute after user deletion. if a script exits non-zero then execution will terminate. 💀
  • /etc/subgid — per user subordinate group IDs.
  • /etc/subuid — per user subordinate user IDs.

✨ EXIT VALUES ✨

she exits with these values, so pay attention:

  1. 0 — success. slay. 🎉
  2. 1 — can't update password file
  3. 2 — invalid command syntax
  4. 6 — specified user doesn't exist
  5. 8 — user currently logged in
  6. 10 — can't update group file
  7. 12 — can't remove home directory

✨ CAVEATS ✨

okay this is the part where we get real with each other:

userdel will not let you remove an account if there are running processes that belong to it. in that case you may have to kill those processes, or lock the user's password or account and remove the account later. the -f option can force the deletion of this account. 👑

you should manually check all file systems to make sure no files remain owned by this user. she's thorough but she's not omniscient, bestie.

you may not remove any NIS attributes on a NIS client. that has to be done on the NIS server. periodt.

if USERGROUPS_ENAB is defined to yes in /etc/login.defs, userdel will delete the group with the same name as the user. to avoid inconsistencies in the passwd and group databases, userdel will check that this group is not used as a primary group for another user, and will just warn without deleting the group otherwise. the -f option can force the deletion of this group. so basically: she double-checks before she goes feral. 🌈

✨ SEE ALSO ✨

go read these next, they're all in the family:

chfn(1), chsh(1), passwd(1), login.defs(5), gpasswd(8), groupadd(8), groupdel(8), groupmod(8), subgid(5), subuid(5), useradd(8), usermod(8).

and that's the whole page bestie!! 💖✨

this lil masterpiece is from shadow-utils 4.20.0, dated 07/30/2026. go forth and delete responsibly, mwah 🫶🎀🦋

📦 where this page comes from