ui-avatars

Deterministic avatar URLs for light and dark designs: Gravatar or Libravatar photos falling back to colored initials via ui-avatars.com. Same input, same URL, always.

Install

pip install ui-avatars

Usage

from ui_avatars import avatar_url

avatar_url(name="Ada Lovelace", email="ada@example.com")
# Gravatar photo, falling back to generated initials

avatar_url(name="Ada Lovelace")
# straight ui-avatars.com URL, no Gravatar lookup

avatar_url(name="Ada Lovelace", email="ada@example.com", image=user.avatar)
# uploaded photo (e.g. Django FieldFile or URL), falling back to Gravatar or initials

avatar_url(email="ada@example.com")
# initials from the first two letters of the email

avatar_url(name="Ada Lovelace", alpha=0.75, size=256, rounded=True)
# pass any of the options as one-off overrides

avatar_url(name="Ada Lovelace", mask="hexagon", format="webp")
# crop the image to a hexagon and serve webp via wsrv.nl

avatar_url(name="Ada Lovelace", email="ada@example.com", source="libravatar")
# look up the photo on Libravatar instead of Gravatar

avatar_url(email="ada@example.com", host="example.com", source="secure.gravatar.com")
# override hostnames to use custom/self-hosted servers

Arguments

At least one of name or email is required.

Name	Description
name	Name used to generate initials
email	Email address used to look up a photo via Gravatar or Libravatar
image	Image URL or file object (supply base if using FileSystemStorage)

Options

Options can be configured globally or overridden per call.

Name	Default	Description
alpha	0.2	Background opacity (0 to 1)
background		Pin the background color
base		Base URL for resolving relative image URLs
bold	True	Bold the initials
colors	RAINBOW_500	List of hex values or (background, text) tuples
font_color		Pin the text color
font_size	0.4	Size of the initials (0.1 to 1)
format		Image format, e.g. png, svg, and other formats
host	ui-avatars.com	User initials avatars host
length	2	Number of initials
mask		Shape mask, e.g. hexagon, pentagon, square, and other masks
proxy	wsrv.nl	Proxy for masks, rounding, and extra formats
region		Service region, e.g. eu or na (ignored if host is set)
rounded	False	Round the image (ignored if mask is set)
size	128	Image size in pixels
source	gravatar	Photo source, e.g. gravatar, libravatar, or any compatible host
uppercase	True	Uppercase the initials

Configuration

Configure the shared avatars instance that avatar_url() uses, or construct your own:

from ui_avatars import avatar_url, avatars, Avatars

avatars.configure(colors=["#1d4ed8", "#b91c1c"], size=256, rounded=True)
avatar_url(name="Ada Lovelace", email="ada@example.com")

my_avatars = Avatars(colors=["#1d4ed8", "#b91c1c"], size=256, rounded=True)
my_avatars.build(name="Ada Lovelace", email="ada@example.com")

Colors

The default color palette is tailwind_colors RAINBOW_500. Swap it for another scale:

from tailwind_colors import TCH

avatars.configure(colors=TCH.RAINBOW_300)
# or make up your own color palette
avatars.configure(colors=["#f00", "#0f0", "#00f"])

Pair colors manually with (background, text) tuples. Set alpha=1 for solid backgrounds:

avatars.configure(alpha=1, colors=[("#f00", "#fff"), ("#000", "#00f")])

To override the palette and force a specific color, pass the color argument:

avatar_url(name="Ada Lovelace", email="ada@example.com", color="#f00")

To pin the background color, text color, or both, pass background and font_color:

avatar_url(name="Ada Lovelace", alpha=1, background="#f00", font_color="#000")

Mixin

from ui_avatars import AvatarMixin, Avatars

class User(AvatarMixin, AbstractUser):
    pass

user.avatar_url

If you want to configure the instance, assign it to avatars on the model:

class User(AvatarMixin, AbstractUser):
    avatars = Avatars(size=64, source="libravatar")

The base option resolves relative image URLs, such as Django's ImageField:

class User(AvatarMixin, AbstractUser):
    profile_picture = models.ImageField(upload_to="profile_pictures", blank=True)

    avatars = Avatars(base="https://example.com")

By default, the mixin uses get_full_name(), full_name, name, first_name and last_name, or username for initials, and avatar, profile_picture, or image for images, in that order.

Override get_avatar_name(), get_avatar_email(), or get_avatar_image() if needed:

class User(AvatarMixin, AbstractUser):
    photo = models.ImageField(upload_to="photos", blank=True)

    def get_avatar_image(self):
        return self.photo

Development

poetry install
poetry run pytest
poetry run ruff check --fix

License

MIT