libravatarserv is a simple libravatar server.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tastytea de7e61a2fe
Update copyright years.
11 months ago
doc Fixed enginx example 1 year ago
src Update copyright years. 11 months ago
.drone.yml Updated the dependency-list to require identiconpp-0.3.4 or above. 1 year ago
.gitignore Initial commit 1 year ago
CMakeLists.txt Bumped version to 0.7.3. 11 months ago
LICENSE Initial commit 1 year ago Update copyright years. 11 months ago
packages.CMakeLists.txt Added automatic package generation 1 year ago

libravatarserv is a simple libravatar server.
It is intended to be used as a
CGI program.

Libravatar is a free service and an open
specification for hosting profile images tied to email or OpenID addresses.


  • Avatar delivery based on email addresses
  • Default avatar for unknown addresses
  • MD5 hashes
  • SHA256 hashes
  • Variable image size (s or size)
  • Default fallbacks (d or default): 404, URL, mp/mm, identicon, retro

The API is explained in greater detail at the
Libravar wiki.

Not supported

  • OpenID
    • Because it isn’t possible to store filenames with ‘/’ in it on most filesystems.
  • The default fallbacks monsterid, wavatar, robohash and pagan
    • Patches welcome
  • forcedefault


Install nginx and
copy the example config to the nginx configuration directory and edit it
according to your needs. Other webservers and cgi spawners will also work, of

Add the following DNS records to your nameserver:     IN SRV 0 0 80 IN SRV 0 0 443 is for HTTP, is for

libravatarserv looks in each of ${XDG_DATA_DIRS} for a directory named
libravatarserv. You can force a different directory by setting the environment
variable LIBRAVATARSERV_DIR (until 0.3.0 AVATAR_DIR).

The image files are named like your email address, no file extension. The
default behaviour for unknown users is to return a 404 error. You can change
that by setting the environment variable LIBRAVATARSERV_DEFAULT_FALLBACK to
any value accepted by d or default. If you want to force a default image for
unknown email addresses, name it default. The default image overrides the
specified fallback in the URL and in the environment variable.

If you want to support “Mystery persons” (mp/mm) as default avatars, place a
file named mp in the avatar dir. You can use the
default libravatar mystery person
(SVG), for example.

Test your setup on


The avatar directory could look like this:

├── [ 32K]  default
├── [ 759]
└── [  16] ->


Configuration is done through environment variables.


The directory containing the avatars.

Default: empty


Controls what happens if no fallback was requested.
Possible values: Anything that can be supplied with the d or default

Default: 404


Set to 1 to redirect to if the user is not found and the
requested fallback is not supported.

Default: 0


Set to 1 to redirect to if the user is not found.

Default: 0

Things to keep in mind

libravatarserv resizes images on the fly and does not cache anything. It also
calculates both MD5 and SHA256 hashes for every user on every request. This
could seriously strain the ressources of your computer if many users use the



Gentoo ebuilds are available via my

Automatically generated packages

Binary packages are generated automatically for each
release in the

  • deb
  • rpm
  • tar.gz

They are generated on Debian Stretch 64 bit and signed with my
automatic signing key.

Up to and including 0.6.2, the packages were generated on Ubuntu 16.04 64 bit.

From source


On a Debian system, install the packages: build-essential cmake libcrypto++-dev libmagick++-dev libxdg-basedir-dev and


mkdir build
cd build
cmake ..
make install
cmake options
  • -DCMAKE_BUILD_TYPE=Debug for a debug build
  • One of:
    • -DWITH_DEB=YES to generate a deb-package
    • -DWITH_RPM=YES to generate an rpm-package

To generate a binary package, execute make package


Contributions are always welcome. You can submit them as pull requests or via
email to


Tests on a laptop with an x86_64 2GHz CPU with 2 cores showed that the average
response time is 140ms with 3 avatars in the “database”, 180ms with 1003
avatars. The tests were done with a 27KiB image, scaled down from 569px to
512px. It took 3,8s / 5-7s to transfer 50 unique avatars (about 3 KiB each) on
one page.



Copyright © 2018, 2019 tastytea <>.
License GPLv3: GNU GPL version 3 <>.
This program comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to redistribute it under certain conditions.