The useradd Command

The useradd command is used on Linux and other Unix-like operating systems both to add new users (also referred to as accounts), inclusive of their user names, passwords and other data, and to update default new user information. The adduser command is identical to useradd, because it is merely a symbolic link to it.

useradd's basic syntax is

useradd [option(s)] username

By default, useradd can only be used by the root (i.e., omnipotent administrative) account. On home computers and other computers over which the user has complete control, the root account can be accessed by logging in as root or, preferably, by using the su (i.e., substitute user) command.

The useradd binary (i.e., the ready-to-run program file) is typically located in the /usr/sbin directory, which contains non-vital system utilities that are used after booting (i.e., starting the system). If this directory is not in the root user's PATH (i.e., the directories in which the system searches for commands issued by the root user), an error message such as bash: useradd: command not found will be displayed. In such case, the command should be typed using its full path (i.e., the full hierarchy of directories from it to the root directory), which would be /usr/sbin/useradd.

To add a new user to the system, all that is necessary is to follow the useradd or adduser command by that user's user name. This name is the login name, that is, the name that the user uses when logging into the system. Only one name can be added with each use of the command, and the name must be unique (i.e., different from every other user name already on the system). Thus, for example, to add a new user with a user name joseph to the system, all that is necessary is to type the following and press the Enter key:

/usr/sbin/useradd joseph

Adding a new user automatically adds an entry to the /etc/passwd file, which is used to store data about users. Each entry in this file consists of a single line containing a set of seven colon-separated fields, for example,


The fields are the user's login name, password (or just the letter x or an asterisk in the likely event that shadow passwords are used), UID (user identification number), GID (group identification number), comment (optional), user's home directory and default shell (usually bash on Linux). On a system with shadow passwords enabled, the actual passwords are encrypted and stored in a separate file which is only accessible to the root account.

/etc/passwd can be edited by the root user with the use of any text editor, such as vi or gedit, and it can be viewed by any user by using one of these editors or by employing a command such as cat, i.e.,

cat /etc/passwd

adduser's flexibility is enhanced by the availability of a number of options. Among the more commonly used is -c, which allows a comment, such as the user's real name and phone number, to be added to /etc/passwd. The comment can be written as a single string (i.e., a sequence of characters without any intervening spaces), or it can be multiple strings enclosed in quotes. For example, the following would add a user named joe and would insert that user's full name, Joe Smith, into the comment field:

useradd -c "Joe Smith" joe

By default the home directory of each user (i.e., the directory that contains a user's personal files and that a user is first in after logging in) will reside in the /home directory and will have the same name as the user. Thus, for example, the default home directory for the new user joe would be /home/joe. However, this behavior can be overriden by using the -d option followed by the full path for the desired new home directory (which need not be in /home). For example, the following would create a new user named jim with a home directory /home/james:

useradd -d /home/james jim

The -e option is used to set the date, in YYYY-MM-DD format, on which the new account will automatically expire. This is useful for creating temporary accounts and for dealing with the tendency of busy system administrators to forget to delete them, which can become a security risk.

The -f option is used to specify the number of days after a password expires until the account is permanently disabled. A value of 0 disables the account as soon as the password has expired. The default value is -1, which disables this feature.

The name or number of the new user's initial login group can be specified by placing it after the -g option. The group name must already exist, and a group number must refer to an already existing group. The default group number is 1 or whatever is specified in the file /etc/default/useradd.

The -G option is used to provide a list of additional groups into which the user is also included. Each group name or number is separated from the next by a comma, with no intervening spaces. The groups are subject to the same restrictions as the group specified with the -g option.

The -m option, which does not accept any arguments (i.e., input data), creates the user's home directory; however, it is not necessary to use it on Red Hat and other systems on which such directory is created automatically. The -k option is used together with -m to specify an alternative to the default /etc/skel directory as the source of the initial content (i.e., directories and files) for the new user's home directory. For example, the following would add the contents of a directory named /dir_1 to /home/jane, which would be the default home directory of a new user jane:

useradd -m -k /dir_1 jane

The -M option is used to create a new user without creating any home directory for that user. When such a user logs into a system that has just booted up, its login directory will likely be the root directory; when such a user logs into a system using the su command, its login directory will be the current directory of the previous user.

On Red Hat systems a new group having the same name as the user being added to the system will be created by default. The -n option is used to prevent such group from being created. The -o option allows creation of a user with a non-unique UID.

The -p option is used to specify an encrypted password that has been created by the crypt command. It is not used to specify the actual password, as this could be a security risk (because such password would be retained in the history file).

The -r option is used to create accounts for administrative use that have some, but not all, root privileges. Such accounts have a UID lower than the value of UID_MIN defined in /etc/login.defs (typically 500 and above for ordinary users) and have a password that does not expire. By default, no home directories are created.

New users are automatically assigned the default login shell, which is bash on Linux unless it has been changed systemwide. However, any new user can be assigned any other shell as their default by using the -s option followed by the name of the desired shell.

The -D option is used to view and change the default values for adding users. The following will display the default settings, which include the initial group, location of the home directory, when the password becomes inactive, when the account expires, the default shell, and name of the directory that contains the directories and/or files that are added automatically to the new home directory:

useradd -D

To change any of the default settings for new users, -D is followed by -g, -b, -s, -f and/or -e, which are, in turn, followed by an appropriate argument. These secondary options are the same as their counterparts described above, with the exception of -b, which stands for base and is followed by the full path of the directory in which new home directories are to be created. Thus, for example, to cause the home directory for new users to be located in a directory called /home/users, the following would be used:

useradd -Db /home/users

Any directory that is specified as the container for new users' home directories need not exist at the time it is specified with -Db. But it must exist when new users are subsequently created. This can, of course, be easily accomplished using the mkdir command, which for the above example would be

mkdir /home/users

As an alternative to using the useradd command, users can also be added and their data changed by directly editing /etc/passwd. However, this is more risky because of the possibility of accidental damage to the file. If a critical system file such as /etc/passwd is to be edited directly, it is, of course, wise to first make a backup copy of it.

After adding a new user, the system administrator uses the passwd command to assign that user a password. User accounts can be removed, preferably, with the userdel command but also by deleting the appropriate line from /etc/passwd.

Created August 31, 2007.
Copyright © 2007 The Linux Information Project. All Rights Reserved.