Migration and Compatibility

Migration and Compatibility

Several WordPress projects have similar names but different jobs. WP User Avatars is deliberately narrow: it stores local avatars and connects them to WordPress's existing avatar APIs.

Direct comparison

Compared against the linked project descriptions on October 6, 2026.

Project	Primary scope	Avatar source and storage	Editing surface	Front-end account features	Relationship to WP User Avatars
WordPress and Gravatar	Core avatar display and defaults	Gravatar or a configured default	Settings > Discussion, with no local per-user upload in WordPress itself	None	WP User Avatars supplies local URLs through the same get_avatar() and get_avatar_url() APIs.
WP User Avatars	Local per-user avatars and a site fallback	Direct upload or WordPress Media Library	Native profile screens, WP User Profiles, block, shortcode	Avatar editor only	This project. It does not create registration, membership, directories, or complete profile pages.
ProfilePress	Memberships, payments, registration, login, profiles, directories, and content restriction	Managed as part of ProfilePress's broader profile system	ProfilePress forms and account interfaces	Broad membership and profile suite	Its WordPress.org slug is wp-user-avatar, but it is a separate project. WP User Avatars does not promise automatic ProfilePress import.
WP User Profiles	Reorganizes WordPress user administration into sections and meta boxes	Uses the avatar provider installed on the site	WordPress administration, Network Admin, and User Dashboard	No standalone membership system	WP User Avatars adds its avatar meta box to WP User Profiles. The plugins are complementary.

Feature descriptions can change. Follow each linked project's current documentation when planning a migration.

WP User Profiles screenshots

Screenshots that show profile fields arranged into tabs, sections, or meta boxes include the companion WP User Profiles plugin. WP User Avatars supplies the avatar controls inside that layout, but it does not create the rest of the profile interface. Install WP User Profiles when that administration layout is the desired result.

No automatic importer

WP User Avatars does not identify or import every legacy avatar plugin's custom metadata. Back up the database and uploads before migration. Test with a small set of users first, and do not remove the source plugin until local avatars render through WordPress's normal APIs.

Import known attachment IDs or URLs

For a controlled one-time migration, pass an attachment ID or URL to the public update function only after validating the source and target:

$user_id       = absint( $user_id );
$attachment_id = absint( $attachment_id );

if (
    $user_id
    && get_userdata( $user_id )
    && wp_attachment_is_image( $attachment_id )
    && wp_get_attachment_url( $attachment_id )
) {
    wp_user_avatars_update_avatar( $user_id, $attachment_id );
}

$user_id    = absint( $user_id );
$avatar_url = wp_http_validate_url( $avatar_url );

if ( $user_id && get_userdata( $user_id ) && $avatar_url ) {
    wp_user_avatars_update_avatar( $user_id, $avatar_url );
}

An integer is treated as a Media Library attachment and records its site ID. A string is treated as a direct URL. On multisite, validate and assign a Media Library attachment while switched to the site that owns it. Updating an avatar removes the previous WP User Avatars assignment before resolving the new value, so retain a tested backup and stop on any validation failure before running a bulk migration.

Adapt existing custom user metadata

When data must remain in another user-meta key, use WordPress's avatar filter instead of copying markup into templates:

add_filter(
    'pre_get_avatar_data',
    function ( $args, $id_or_email ) {
        $user_id = wp_user_avatars_get_user_id( $id_or_email );
        $url     = $user_id ? get_user_meta( $user_id, 'my_avatar_url', true ) : '';

        if ( $url && empty( $args['url'] ) ) {
            $args['url']          = esc_url_raw( $url );
            $args['found_avatar'] = true;
        }

        return $args;
    },
    20,
    2
);

This adapter leaves the original metadata in place. A native WP User Avatars assignment still takes precedence when one exists. Put production adapters in a small site plugin or must-use plugin, not in WP User Avatars itself.

Translation files

The plugin text domain is wp-user-avatars. WordPress.org language packs are the preferred translation path. WordPress installs those files under wp-content/languages/plugins/ with names such as wp-user-avatars-de_DE.mo and wp-user-avatars-de_DE.l10n.php.

Do not rename a translation for a different text domain, and do not edit the plugin files. An update will replace changes stored inside the plugin directory.