This article belongs to the Flask Common Extensions Introduction series, and an index of the contents of this series can be found in the Flask Common Extensions Introduction Series Index.


Most Web applications involve the implementation of an avatar. Different types of projects require different avatars. Some projects can use Gravatar directly, while others require custom avatars. Flask-avatars has almost all the usual Avatars requirements:

  • The default avatar
  • them
  • Robohash avatar
  • Social networking profile picture
  • Generate Identicon random pattern head
  • Picture cropping head

GitHub homepage:…

Installation and initialization

Install with PIP:

$ pip install flask-avatarsCopy the code

Like other extensions, you need to instantiate the Avatars class imported from Flask_Avatars and pass in the app instance:

from flask_avatars import Avatars

app = Flask(__name__)
avatars = Avatars(app)Copy the code

If you use the factory function to create an instance of the program, you can pass in the app instance instead of the app instance and pass in the app instance when you call the init_app() method on the avatars object in the factory function.

The default avatar

Flask-avatars has several default Avatars built in, which can be used as a user’s initial Avatars after signing up, or as a blog commenter’s Avatars. Call avatars.default() in the template to get the URL:

<img src="{{ avatars.default() }}">Copy the code

You can set the size using the size parameter. The default value is m. Other options are L and S. An example of an actual call is as follows:


To get a gravatar(, call avatars.gravatar() and pass in the Email hash value:

<img src="{{ avatars.gravatar(email_hash) }}">Copy the code

The Email hash value can be obtained as follows:

import hashlib

avatar_hash = hashlib.md5(my_email.lower().encode('utf-8')).hexdigest()Copy the code

An example of an actual call is as follows:


Robohash ( is a service that generates random robot avatars (this type is currently supported in the default Gravatar avatar, which can be obtained by setting the default parameter to Robohash). To get the avatar URL of RoboHash, call avatars.robohash() in the template and pass random text as an argument:

<img src="{{ avatars.robohash(some_text) }}">Copy the code

An example of an actual call is as follows:

Social networking profile picture

Flask-avatars offers a social avatar acquisition service via and currently supports Facebook, Twitter, Instagram and Gravatar. Call avatars.social_media() in the template and pass in the username (username) to get the corresponding avatar URL. The size parameter can be used to set the size. The optional values are small, medium, and large:

<img src="{{ avatars.social_media(username) }}">Copy the code

The platform parameter allows you to set the platform. The default is Twitter, and the optional values are Twitter, Facebook, Instagram, and gravatar:

<img src="{{ avatars.social_media(username, platform='facebook') }}">Copy the code

An example of an actual call is as follows:

Generate Identicon random pattern head

The Gravatar service may have unstable conditions, in which case you can generate an avatar for the user locally (Identicon). Here is a simple example:

app.config['AVATARS_SAVE_PATH '] = 'the/path/to/save/avatar'Avatar = Identicon() filenames = avatar. Generate (text= 'a string of only characters')Copy the code


from flask import send_form_directory, current_app

def get_avatar(filename):
    return send_from_directory(current_app.config['AVATARS_SAVE_PATH'], filename)Copy the code

The following is an example of the generated profile picture:

Cutting head

Flask-avatars provides the image cropping function based on Jcrop. For details, please refer to the documentationRelevant part. Here is the cropped page in the sample program:

Cropped results:


Flask-avatars supports the following configuration list:

configuration The default value instructions
AVATARS_GRAVATAR_DEFAULT identicon Gravatar Default avatar type
AVATARS_SAVE_PATH None Path for Saving profile pictures
AVATARS_SIZE_TUPLE (30, 60, 150) Head size three-element tuple in the format of(small, medium, large), used to generate identicon head and cropping head
AVATARS_IDENTICON_COLS 7 Identicon Number of color blocks in a row of the head
AVATARS_IDENTICON_ROWS 7 Identicon Number of color blocks in a head column
AVATARS_IDENTICON_BG None Identicaon background color of the head, passed in RGB tuple, e.g(125, 125, 125). Random colors are used by default
AVATARS_CROP_BASE_WIDTH 500 Crop the display width of the picture
AVATARS_CROP_INIT_POS (0, 0) Clipping box starting position, two-element tuple (x, y), default upper left corner
AVATARS_CROP_INIT_SIZE None The size of the clipping box is the size L set in the size tuple by default, that isAVATARS_SIZE_TUPLE[0]
AVATARS_CROP_MIN_SIZE None The minimum size of the clipping box, unlimited by default
AVATARS_CROP_PREVIEW_SIZE None The size of the preview window, by default, is the m size set in the size tuple, i.eAVATARS_SIZE_TUPLE[1]
AVATARS_SERVE_LOCAL False Whether to load Jcrop resources locally, by default, from the CDN

The sample program

Flask-avatars Git repository contains three instance programs, which correspond to the screenshot in this article:

  • Examples/Basic – Basic examples
  • Examples /identicon — identicon example
  • Examples /crop — clipping examples

You can run the instance as follows:

$ git clone
$ cd flask-avatars/examples
$ pip install flask flask-avatars
$ cd basic  Switch to the identicon and Crop directories to run the corresponding sample programs
$ flask runCopy the code

A link to the

  • GitHub homepage:…
  • Flask, series index extensions
  • Them…