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.

Options

Options can be configured globally or overridden per call.

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 is used to resolve 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")

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