You should probably just use one of the available libraries or plugins, but here is a description of the API.
There are 4 steps for displaying Libravatar-hosted images into your application:
- Create a hash from the user's email address: a. Lowercase the email address. b. Compute a MD5 or SHA256 hash of it.
- Discover the avatar server base URL:
a. Use DNS-based server discovery as described in Federated Servers.
b. If no server was found, fall back to
- Create a URL like
- Put the URL into an
imgtag on your page.
Here's an example in Python:
import hashlib email = 'George@example.com'.encode('utf-8') hash = hashlib.md5(email.strip().lower()).hexdigest()
which gives us a hash of 40f8d096a3777232204cb3f796c577b7 and therefore the following image tag:
<img src="https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7" alt="avatar of firstname.lastname@example.org"/>
The default size for images is 80x80 pixels, however you can change it by providing an extra parameter to the URL:
The s or size is the size (height and width are the same) of the image in pixels. Acceptable values range from 1 to 512.
Default URL for missing images
If you would like to specify a default "missing image" picture for email addresses which are not found in the Libravatar database, you may specify the URL of an image to redirect to:
The d or default parameter defaults to the Libravatar logo, but a few other special values are available:
- 404: return a 404 error (file not found) instead of an image
Note that if an image is not found in the Libravatar database and the hash algorithm used was MD5, then Libravatar will first redirect to Gravatar in case the image exists there. Then it will honour the default parameter.
For Gravatar users
As you can see, our API is heavily based on the Gravatar API. If your application or website already supports Gravatar switching to the basic Libravatar service is just a matter or changing the base URL:
http://www.gravatar.com/avatar => http://cdn.libravatar.org/avatar
or if you are using the HTTPS version of the service:
https://secure.gravatar.com/avatar => https://seccdn.libravatar.org/avatar
Note that Libravatar does not support the rating (or simply r) parameter since we require all images to be G-rated.
In order to support domain name owners who choose to run their own instances of Libravatar, you must perform a DNS query to lookup the appropriate base URL for each domain (the domain is extracted from email addresses or OpenID URLs).
DNS host names:
You will probably want to use an existing library for this, but here's how to do that DNS lookup on a UNIX command line:
$ dig +short SRV _avatars._tcp.example.com 0 0 80 avatars.example.com.
We also provide a domain check tool to help in your testing.
Notes for advanced users / library authors:
- Libravatar clients only consider servers listed in the highest SRV priority.
- They do however honour relative weights.
- SRV records are cached for at least 1 day (or more if the TTL is greater than 1 day).
- Make sure you sanitize the results you get from the DNS resolver (see Perl and Python examples).
If your application is delivered over a secure (HTTPS) connection, you may want to use our HTTPS image servers to avoid triggering browser warnings about mixed HTTP/HTTPS content.
To do so, simply use this base URL:
When looking up the base URL to use via DNS, replace _avatars._tcp.example.com with:
In addition to email addresses, Libravatar allows users to associate photos to their OpenIDs.
The same 5 steps apply:
- Take a user's OpenID URL as entered by them.
- Convert the protocol and hostname parts of the URL to lowercase. e.g. HTTP://UserName:Password@EXAMPLE.COM/ID/Bob => http://UserName:Password@example.com/ID/Bob
- Compute the hash (using the SHA256 hash algorithm only).
- Turn the image into a URL by prefixing it with the Libravatar base URL.
- Put the image into an img tag on your page.
Therefore, if you don't have an email address for some of your users but you do have OpenID URLs, here is sample Python code to produce a hash for them:
import hashlib from urlparse import urlsplit, urlunsplit openid = 'http://example.com/id/john' url = urlsplit(openid.strip()) if url.username: password = url.password or '' netloc = url.username + ':' + password + '@' + url.hostname else: netloc = url.hostname lowercase_url = urlunsplit((url.scheme.lower(), netloc, url.path, url.query, url.fragment)) hash = hashlib.sha256(lowercase_url).hexdigest()
We provide a check tool to help developers test their implementations and compare their results.