Every WordPress site that displays author avatars or comment profile pictures relies on Gravatar for images, a global service that maps email addresses to profile photos. When a user’s email address has no associated Gravatar account, WordPress displays a default fallback image. The default fallback is the “mystery person”, a grey silhouette, or one of several alternative generic options like a geometric pattern or a retro game character. None of these are on-brand for most sites.
This snippet replaces the Gravatar fallback with your own image, giving unrecognised users a consistent, branded avatar that fits your site’s visual style.
The Code
Add this to your functions.php or a site-specific plugin. Upload your custom avatar image to your theme’s /images/ directory as default-avatar.png, or adjust the path in both filter callbacks to wherever you store the image.
The Two Filters
Two filters work in combination here. The first, avatar_defaults, adds your custom image to the list of options shown in Settings → Discussion → Default Avatar, making it selectable from the admin UI. After adding it, go to that settings page and select “Custom Avatar” from the list to make it the site-wide default.
The second filter, get_avatar_url, programmatically overrides the URL for any avatar request that would otherwise return Gravatar’s mp (mystery person) default. It checks whether the URL contains both gravatar.com/avatar and d=mp (the mystery person parameter), and only replaces those, leaving any user who has a real Gravatar or uploaded avatar completely unaffected.
Image Specifications
Gravatar images are displayed as squares at various sizes depending on the context, typically 48px to 96px for comments and author bios, up to 150px or larger in some theme layouts. Your custom avatar should be a square image at a minimum of 150×150 pixels. PNG with transparency works well if the avatar is designed to sit on different background colours. A simple, clean icon or a branded monogram tends to work better than a photo placeholder at small sizes.
Privacy Benefit
Replacing the Gravatar default with a locally hosted image has a secondary privacy benefit: it prevents the browser from making a request to gravatar.com for users without a Gravatar account. The Gravatar request includes a hashed version of the user’s email address and can be used to track which users visit which sites. Serving a local fallback eliminates this third-party request for unregistered users.
Disabling Gravatar Entirely
If you want to disable Gravatar lookups completely and use only local avatars, for example on sites with strict data protection requirements, set the get_avatar_url filter to always return your local image regardless of whether a Gravatar exists. Combine this with a plugin like Simple Local Avatars that lets users upload their own avatar directly to WordPress without relying on Gravatar at all.
add_filter( 'avatar_defaults', function( $avatar_defaults ) {
$custom_avatar = get_stylesheet_directory_uri() . '/images/default-avatar.png';
$avatar_defaults[ $custom_avatar ] = 'Custom Avatar';
return $avatar_defaults;
} );
// Force the custom avatar as the default for all get_avatar() calls
add_filter( 'get_avatar_url', function( $url, $id_or_email, $args ) {
// Only replace the Gravatar default, not custom uploaded avatars
if ( strpos( $url, 'gravatar.com/avatar' ) !== false && strpos( $url, 'd=mp' ) !== false ) {
return get_stylesheet_directory_uri() . '/images/default-avatar.png';
}
return $url;
}, 10, 3 );