Ready to get started?Download WordPress


Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get users


Retrieves an array of users matching the criteria given in $args.


 <?php get_users$args ); ?> 


<?php $args = array(
'blog_id' => $GLOBALS['blog_id'],
'role' => '',
'meta_key' => '',
'meta_value' => '',
'meta_compare' => '',
'include' => array(),
'exclude' => array(),
'orderby' => 'login',
'order' => 'ASC',
'offset' => '',
'search' => '',
'number' => '',
'count_total' => false,
'fields' => 'all',
'who' => ''
 ); ?>
  • blog_id - The current blog's ID, unless multisite is enabled and another ID is provided
  • role - Limit the returned authors to the role specified.
  • include - An array of IDs. Only users matching these IDs will be returned.
  • exclude - An array of IDs. Users matching these IDs will not be returned, regardless of the other arguments.
  • meta_key - The meta_key in the wp_usermeta table for the meta_value to be returned. See get_userdata() for the possible meta keys.
  • meta_value - The value of the meta key.
  • meta_compare - Operator to test the 'meta_value'. Possible values are '!=', '>', '>=', '<', or '<='. Default value is '='.
  • orderby - Sort by 'nicename', 'email', 'url', 'registered', 'display_name', or 'post_count'.
  • order - ASC (ascending) or DESC (descending).
  • offset - The first n users to be skipped in the returned array.
  • search - Use this argument to search users by email address, URL, ID or username (this does not currently include display name).
  • number - Limit the total number of users returned.
  • count_total - False by default.
  • fields - Which fields to include in the returned array. Default is "all". It appears one can also request 'all_with_meta'. Other Possible values appear to be those in the main user table (in 3.2.1). Previous documentations advised : fields are the same as those for meta_key. However use of meta_keys gives a SQL error.
  • who - If set to 'authors', only authors (user level greater than 0) will be returned.


A basic example to display all subscribers in an unordered list.

    $blogusers = get_users('blog_id=1&orderby=nicename&role=subscriber');
    foreach ($blogusers as $user) {
        echo '<li>' . $user->user_email . '</li>';

An example using the 'search' field.

    $blogusers = get_users('search=john');
    foreach ($blogusers as $user) {
        echo '<li>' . $user->user_email . '</li>';

This example will find and display all users that have a user name, ID, email of "john". You can also do wild card search by adding an * before or after your search query. For example, to search for all users that start with "jo", you do this:

    $blogusers = get_users('search=jo*');
    foreach ($blogusers as $user) {
        echo '<li>' . $user->user_email . '</li>';

The results will be all users whose user names, IDs, or emails that start with "jo". The * can be placed before or after your search query. When placed before, the results will be all users that end in your query.


array of user objects, except when fields= specifies a single Field to be returned, then an array of values is returned.

Example of Object return

   [ID] => 1
   [user_login] => admin
   [user_pass] => $P$Bxudi6gJMk2GRt2ed3xvZ06c1BPZXi/
   [user_nicename] => admin
   [user_email] => admin@host.com
   [user_url] => http://localhost/
   [user_registered] => 2010-06-29 07:08:55
   [user_activation_key] => 
   [user_status] => 0
   [display_name] => Richard Branson

Example for Array of Values when single Field specified

   0 => Richard Branson
   1 => Winston Churchill


Since: Version 3.1

Source Code

get_users() is located in wp-includes/user.php.

See also index of Function Reference and index of Template Tags.