How to implement Gravatar on your site

In my last post, I gave an introduction of Gravatar, a web service that streamlines the management of profile images associated with an email address and enables them to be shown at multiple sites. You will notice how useful the service is as more and more services around the world get to support Gravatar. In this post, I will explain how to implement Gravatar on your site.

What is Gravatar?

Gravatar is a web service that associates profile images with your email address. A lot of services such as WordPress, github, and Redmine support Gravatar. You first register your email address and profile image, and then the URL for the accessing profile image will be issued based on the hash of the email address. Different sites can display the same profile image by calling the URL.

What is good about Gravatar?

It helps developers handle profile images

For web developers, handling profile images would be a bit of pain – creating a saving logic, preparing cache, making different sizes of images, and uploading… All you need is an email address. Gravatar will do the job for you.

Also good for users

With Gravatar, the same image can be applied to different sites. Users do not need set their profile image at each site; they can replace their profile image on different sites at one go.

Filter out inappropriate images

Gravatar provides a self-rating system. Avatars reported as provocative or violent materials by the user (uploader) can be replaced with default images by the administrator of the service site.


💡 The contents of this section are based on a reference Creating the Hash.
Gravatar searches for a profile data based on the MD5 hash of the email address. The following rules must be followed to create an accurate hash.

– Trim leading and trailing whitespace from an email address (the trim function in PHP)
– Force all characters to lower-case (the strtolower function in PHP)

The following is an example of the statement written in a single line:

echo md5( strtolower( trim( "[email protected] " ) ) );

You can request an image using a hash calculated this way.

Image API

💡 I took reference to Image Requests to write this section.

The most basic image request URL looks like this:

To request a Gravatar image, “HASH” need to be replaced with the calculated hash.

<img src="" alt="Gravatar" />

This code returns an image as below.


You can customize the request by adding query strings. All the query strings introduced below can be combined to produce more complex/refined requests.

size ( or s )

The default image size is 80px by 80px, which can be changed by passing a size parameter. You can set the parameter to between 1px and 512 px inclusive. A too large value may degrade some images.

default ( or d )

When an email address has no matching Gravatar image or the image does not meet the requested rating level, a default image, a Gravatar’s logo, is displayed. You can replace it with your own default image.

Gravatar has a number of built-in options which you can use as defaults. The options include:
– 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response.
– mm: (mystery-man) a simple, cartoon-style silhouetted outline of a person.
– identicon, monsterid, wavatar, retro: automatically generated.

You can use Gravatar’s size option to maintain the quality of built-in default images in any size. To use your own image, specify the URL (which should be URL-encoded).

The following images have been generated base on the hash of an email address which does not exist and thus differs from that used for the images shown in the Image Requests page. Note that the automatically generated images look all different.







Default images shown in the Image Requests page

forcedefault ( or f)

This option forces a default image to always be loaded. You could use it if you wanted to force users to use only auto-generated default images rather than their original images.

rating ( or r)

Gravatar’s image rating system filters out some images. The rating is self-reported by the user, but you can forbid some images that you think are inappropriate for your site. The rating criteria (cited from the Image Requests page) is as follows:

g: suitable for display on all websites with any audience type.
pg: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
r: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
x: may contain hardcore sexual imagery or extremely disturbing violence.

If you want to permit only rated G/PG images, you should specify “r=pg”, which replaces rated R/X images with one of the above-mentioned default images.


(Though, strictly speaking, it is not a query string, if you require a file-type extension, you may add an .jpg extension immediately to the end of a hash. 

I have confirmed that other types of extension such as .png and .bmp return an image, but it is JPEG format. You can do the same for SSL websites by changing the beginning of the URL like this:

Sample libraries

Developer resources publicizes sample codes in various languages. You can also have a look at Plugins, Libraries & Implementations to check out the list of libraries, plugins, applications, etc. posted by third parties. These resources will be a great help to encourage you to implement Gravatar to your web service.

This post is also available in other languages.