How to create WordPress users programmatically

Today we’ll take a deep dive into how to create WordPress users programmatically. Throughout this article, we look into how to use the wp_create_user() and wp_insert_user() functions. In addition, we’ll compare them and find out where to use each WordPress user function. Furthermore, we’ll explore how to create users with user meta. And in the end, we’ll explore how to better visualize, and filter users based on these custom fields.

You can always create users by using the WordPress dashboard. But this approach is not enough in case you need to programmatically create WordPress users. In these cases, we need to use some PHP code.

However, this decision is not always so simple. That’s because WordPress has more than one function to create users. Thus, we need to check the characteristics of each function, then evaluate which one is better for our needs.

In addition, creating users alone may not be enough for our project. Usually, we need to add custom user fields and data to better organize our users.

That’s our goal for today, to walk from the very basic syntax of these functions to their core differences. Then we’ll dive into their usage comparison and understand how to create users with their custom fields.

creating wordpress users programmatically

The wp_create_user() function

wp_create_user() is a simple function to create a new WordPress user. This function accepts just 3 arguments – the username (required), password (required) and email (optional). When successful, it returns the newly created user ID. If there’s an error, you get a WordPress error object.

This is its basic syntax:

And here is an example of using this function:

Since the email is optional, this is one of the few ways you can use to create WordPress users with no emails. The following example illustrates a quick way to create users with no email:

You may be wondering about error handling. After all, we don’t want to create WordPress users programmatically where there are conflicts. The beauty of the wp_create_user() WordPress function is that it handles the error cases for you. Thus, you just need to check for the result of the function and see if that’s an ID or a WP error. You can check whether a value is an error by using the is_wp_error() functon.

And this is how the data looks like in the database when the code is executed successfully:

Result of wp_create_user() function in the database

The wp_insert_user() function

The wp_insert_user() function is the big brother of the wp_create_user() function. This function has a lot more options when it comes to programmatically creating WordPress users. And with great powers come great responsibility. Here we need to prepare our data to account for all these options.

The base syntax for wp_insert_user() is this one:

But the true secret is inside of the $user_data argument. This can be either an array, an instance of stdClass or an instance of WP_User. These are the possible values for an array formatted data:

Additionally, even though this function is called “insert user”, it can be used to update users. That’s why all arguments can be null. If you add the user ID, you just need to add the arguments you want to update. If you don’t add a user ID, then a new user will be created with your parameters. However, if you need to update a user, it’s better to use the wp_update_user() function instead. In this way, your code will be much easier to read and understand.

Similarly, this function returns the user’s ID on success and a WordPress error object on failure.

The following example illustrates creating a new user by setting some additional data:

It is a bit fuzzy, as this syntax requires you to create an array. But this case is much more powerful. Thus, we trade more options for a harder setup. This is how the result looks in the wp_users table:
Result of wp_insert_user() function in the database

And the additional fields, such as first/last name and role can be found in the wp_usermeta table:

Result of wp_insert_user() function in the database meta table

wp_create_user() vs wp_insert_user()

As you may have noticed, both functions are quite similar. And that’s for a good reason. The truth is that the wp_create_user() function actually calls the wp_insert_user() function. This is how WordPress creates this function in the core:

Therefore, no matter what you pick, both functions are going to lead to very similar results. Thus, it’s a matter of how much data you need to specify for the user. If you just need to specify username, password and email, go for wp_create_user(). On the other hand, if you need a more robust setup, where you need to specify more user fields, wp_insert_user() is better.

Now let’s add custom fields to our users.

Creating users with custom meta fields

The wp_insert_user() function allows metadata addition and customization. But in order to add custom user fields, you need to use the update_user_meta() function. The syntax is quite simple, we use it like this:

Since this function can only add one custom field at a time, we need to take this into account. Thus, if you want to create users along with their metadata, you need a loop. This example creates a user, then we add a job title and country custom fields. But if you have more custom fields you can just add them to the array we set up.

Therefore, this function creates users with custom fields. You can freely tweak this function, in particular regarding the custom fields you accept. If the data comes from a user submitted form, make sure to correctly escape and verify meta values, to avoid security issues.

Here we add the viaphp flag to our users as well. This is a quick way to filter users who have been created by using our functions. That’s quite handy in case you need to troubleshoot issues with these users.

How to filter the programmatically created WordPress users

As we created 3 custom user fields, we can use them to filter these users with Users Insights. For that, the first step is to map these custom fields under Users Insights > Custom Fields. You just need to add your field keys there so that they can be used in our user table. In case you need more information, you can read our guide on how to map custom user fields.

There are many ways to search, filter and display users based on metadata. However, here we are focused on the power of filtering WordPress users created via code. Once you have the Via PHP custom field mapped, we can filter all dynamically created WordPress users:
Filter programatically created users
Then we have the regular filters. For instance, if you want to know how many developers you have in your database you can filter users based on their job title:
Filter WordPress users who are developers
The true power of Users Insights comes from combining filters. For example, if you have a product that is targeted to local developers only it is easy to find them. You just need to filter users based on their Country AND Job title. Something like this:
Filter users based on multiple criteria
This should be enough to get started. Now the sky is the limit!


Today we looked into how to create WordPress users programmatically. We learned how to use the wp_insert_user() and wp_create_user() functions. In addition, we dived into their particularities and differences. Then we created users with custom fields and filtered through them using Users Insights.

We hope you enjoyed this article and see you again next time!