This article will show you different methods to programmatically delete users with WordPress.

Programmatically deleting users involves using the PHP language and dedicated functions provided by WordPress. It’s an alternative to manually deleting WordPress users, which developers can use in many circumstances.

If you are a WordPress developer, you can, for example:

  • Delete WordPress users from a custom UI
  • Delete WordPress users based on custom conditions that occur in the WordPress environment
  • Remove inactive users
  • Bulk delete users when you are dealing with a significant amount of data or automatically delete users based on custom criteria
  • Provide the ability to the users to delete their account from dedicated plugin features

Basic example to programmatically delete a user

To delete a user we will use the wp_delete_user() function. This function takes two parameters. The first parameter should be used to specify the user that we want to delete, while the optional second parameter indicates to which user we want to transfer the content of the deleted user.

Before using this function, we need to include the file where the function is declared, specifically the wp-admin/includes/user.php file.

The example below demonstrate how to programmatically delete a user given a specific user ID.

/**
 * Delete a user based on the specified ID.
 *
 * @param $user_id
 *
 * @return bool
 */
function delete_user( $user_id ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	//Delete a WordPress user by specifying its user ID. Here the user with an ID equal to $user_id is deleted.
	return wp_delete_user( $user_id );

}

//Delete the user with ID equal to 3
delete_user(3);

Suppose your script runs in a context where it’s essential to provide feedback to the user. In that case, you should also consider using the return value of the wp_delete_user() function to echo a message or activate other mechanisms to provide feedback.

With the instructions below, the return value of the wp_delete_user() function is used to echo a message:

if ( wp_delete_user( $user_id ) ) {
	echo "The user has been successfully deleted.";
} else {
	echo "This user can't be deleted";
}

Be aware that the script considered in this section deletes all the posts and metadata associated with the user. The content generated by a user can be transferred to another user using the second parameter of the wp_delete_user() function, which I will cover in the next section.

Delete a user and reassign its content

We are now going to use the second parameter of the wp_delete_user() function to programmatically delete a WordPress user and at the same time reassign his content, specifically his posts and metadata, to another user.

/**
 * Delete the specified user and reassign its content to another user.
 *
 * @param $user_id
 * @param $user_id_reassign
 *
 * @return bool
 */
function delete_user_and_reassign_content( $user_id, $user_id_reassign ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	/**
	 * Delete a WordPress user by specifying its user ID. In this example user 2 is deleted, its content is then
	 * reassigned to user 4.
	 */
	return wp_delete_user( $user_id, $user_id_reassign );

}

//Delete user 2 and reassign its content to user 4
delete_user_and_reassign_content(2, 4);

Delete a user by username

When developing a plugin or theme, you can also delete a user based on values other than the user id.

In the example below, I first use the get_user_by() function to retrieve a specific user object from a username. Then I use the user ID available in the user object to delete the user with the wp_delete_user() function.

/**
 * Delete the user with the specified username.
 *
 * @param $username
 *
 * @return bool
 */
function delete_user_by_username( $username ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	//Include the file with the pluggable functions, which includes the get_user_by() function
	require_once( ABSPATH . 'wp-includes/pluggable.php' );

	$user = get_user_by( 'login', $username );

	return wp_delete_user( $user->ID );

}

//Delete the user with username "john123"
delete_user_by_username('john123');

Delete the user based on its email

Note that with the get_user_by() function, you also can retrieve the user object from other characteristics like the user ID, slug, email address, or login name. The following example is similar to the one available in the previous section. However, now we get the user based on its email.

/**
 * Delete the user with the specified email.
 *
 * @param $username
 *
 * @return bool
 */
function delete_user_by_email( $email ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	//Include the file with the pluggable functions, which includes the get_user_by() function
	require_once( ABSPATH . 'wp-includes/pluggable.php' );

	//Get the user object from the provided email
	$user = get_user_by( 'email', $email );

	return wp_delete_user( $user->ID );

}

delete_user_by_email( '[email protected]' );

Programmatically delete users with a specific role

To mass delete users by their role, you can first retrieve a collection of users belonging to that specific role with the get_users() function and then iterate and delete them.

In detail, to get the users with a specific role, we will use the get_users() function and the role parameter. It’s worth noting that you can include an array or a comma-separated list of user roles in this parameter.

For non-inclusive lists of roles, consider using role__in. Additionally, there is also the role__not_in parameter if you want to exclude specific roles from the resulting lists. More information on the parameters allowed with get_users() is available on the WP_User_Query documentation page.

/**
 * Delete all the users that belong to the specified role.
 *
 * @param $role
 */
function delete_users_by_role( $role ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	//Get a list of users that belongs to the specified role
	$users = get_users( array( 'role' => array( $role ) ) );

	//Delete all the user of the specified role
	foreach ( $users as $user ) {
		wp_delete_user( $user->ID );
	}

}

//Delete all the users with the role of Author
delete_users_by_role('author');

Delete users with a specific capability

You can also programmatically delete users based on the capabilities associated with their roles. For example, the script below does exactly this by iterating through the users and then checking the capability with the user_can() function.

Note that to avoid errors caused by the use of the wp_delete_user() with the WordPress administrator (you can’t programmatically delete the WordPress administrator with this function), the script, before proceeding, also checks if the considered user is an administrator.

/**
 * Delete all the users that have the specified capability.
 *
 * @param $capability
 */
function delete_users_by_capability( $capability ) {

	//Include the user file with the user administration API
	require_once( ABSPATH . 'wp-admin/includes/user.php' );

	//Get a list of users that belongs to the specified role
	$users = get_users();

	//Delete all the user of the specified role
	foreach ( $users as $user ) {

		//Deleting the administrator causes error. As a consequence we verify if the user is an administrator before proceeding.
		if ( ! in_array( "administrator", $user->roles ) ) {

			//Delete this user only if it has the specified capability
			if ( user_can( $user, $capability ) ) {
				wp_delete_user( $user->ID );
			}

		}

	}

}

//Delete all the users with the "custom1" capability
delete_users_by_capability('custom1');