Skip to content


Repository files navigation



travis Coverage Status Code Climate dependency status devDependency status docs status

Crafatar serves Minecraft avatars based on the skin for use in external applications. Inspired by Gravatar (hence the name) and Minotar.

Image manipulation is done by lwip. 3D renders are created with node-canvas / cairo.

Contributions welcome!

There are usually a few open issues.
We welcome any opinions or advice in discussions as well as pull requests.
Issues tagged with help wanted show where we could especially need your help!


jomo's avatar Jake_0's avatar Notch's avatar sk89q's avatar
jomo's 3d head Jake_0's 3d head Notch's 3d head sk89q's 3d head
jomo's 3d body Jake_0's 3d body Notch's 3d body sk89q's 3d body
jomo's skin Jake_0's skin Notch's skin sk89q's skin

Usage / Documentation

Please visit the website for details.




docker network create crafatar
docker run --net crafatar -d --name redis redis
docker run --net crafatar -v crafatar-images:/home/app/crafatar/images -e REDIS_URL=redis://redis -p 3000:3000 crafatar/crafatar


  • Install nodejs 12 (LTS)
  • Install redis-server
  • Run npm install
    If that fails, it's likely because because of node-canvas dependencies. Follow this guide to install them.
  • Run npm start

Crafatar is now available at

Configration / Environment variables

See the config.js file.

Operational notes


Crafatar stores a lot of images on disk. For avatars, these are 8×8 px PNG images with an average file size of ~90 bytes. This can lead to issues on file systems such as ext4, which (by default) has a bytes-per-inode ratio of 16Kb. With thousands of files with an average file size below this ratio, you will run out of available inodes before running out of disk space. (Note that this will still be reported as ENOSPC: no space left on device).

Consider using a different file system, changing the inode ratio, or deleting files before the inode limit is reached.

disk space and memory usage

Eventually you will run out of disk space and/or redis will be out of memory. Make sure to delete image files and/or flush redis before this happens.


npm test

If you want to debug failing tests:

# show logs during tests
env VERBOSE_TEST=true npm test

It can be helpful to monitor redis commands to debug caching errors:

redis-cli monitor