update_user_meta( int $user_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' )

Update user meta field based on user ID.

Description Description

Use the $prev_value parameter to differentiate between meta fields with the same key and user ID.

If the meta field for the user does not exist, it will be added.

Top ↑

Parameters Parameters


(int) (Required) User ID.


(string) (Required) Metadata key.


(mixed) (Required) Metadata value.


(mixed) (Optional) Previous value to check before removing.

Default value: ''

Top ↑

Return Return

(int|bool) Meta ID if the key didn't exist, true on successful update, false on failure.

Top ↑

More Information More Information

Changes in behavior from the now deprecated update_usermeta:

Update_user_meta does not delete the meta if the new value is empty.

The actions are different.

Top ↑

Source Source

File: wp-includes/user.php

function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
	return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );

Top ↑

Changelog Changelog

Version Description
3.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    how to check for errors

    $user_id = 1;
    $new_value = 'some new value';
    // Will return false if the previous value is the same as $new_value.
    $updated = update_user_meta( $user_id, 'some_meta_key', $new_value );
    // So check and make sure the stored value matches $new_value.
    if ( $new_value != get_user_meta( $user_id,  'some_meta_key', true ) ) {
    	wp_die( __( 'An error occurred', 'textdomain' ) );
  2. Skip to note 2 content
    Contributed by kimdcottrell

    update_user_meta() will update ALL user meta of the same key UNLESS you specify a specific record out of the set that you want to replace.

    Here’s a way to do that, specifically for the instance where you have user meta that may look like this:

    | user_id | meta_key             | meta_value                                                                                               |
    | 862     | favorite_coffee      | {"coffee_id":10,"title":"Vietnamese Iced Coffee","type":"drip"}                                          
    | 862     | favorite_coffee      | {"coffee_id":11,"title":"Mocha","type":"espresso"}                                                       
    | 862     | favorite_coffee      | {"coffee_id":12,"title":"Just An Okay Cappuchino","type":"espresso"}
    // dummy data to better show the issue, we want to change the title of `coffee_id` 12
    $parameters = array(
        'coffee_id' => '12',
        'title' => 'A Delicious Cappuchino',
        'type' => 'espresso',
    // try to find some `favorite_coffee` user meta 
    $previous_favorite_coffee = get_user_meta( $user_id, 'favorite_coffee', false );
    * First, the condition for when no favorite_coffee user meta data exists
    if ( empty( $previous_favorite_coffee ) ) {
        add_user_meta( $user_id, 'favorite_coffee', $parameters );
    * Second, the condition for when some favorite_coffee user_meta data already exists
    // search recursively through records returned from get_user_meta for the record you want to replace, as identified by `coffee_id` - credit: http://php.net/manual/en/function.array-search.php#116635
    $coffee_id = array_search( $parameters['coffee_id'], array_column( $previous_favorite_coffee, 'coffee_id' ) );
    if ( false === $coffee_id ) {
        // add if the wp_usermeta meta_key[favorite_coffee] => meta_value[ $parameters[ $coffee_id ] ] pair does not exist
        add_user_meta( $user_id, 'favorite_coffee', $parameters );
    } else {
        // update if the wp_usermeta meta_key[favorite_coffee] => meta_value[ $parameters[ $coffee_id ] ] pair already exists
        update_user_meta( $user_id, 'favorite_coffee', $parameters, $previous_favorite_coffee[ $coffee_id ] );

You must log in before being able to contribute a note or feedback.