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(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

Options

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")

Development

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

License

MIT