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)
# alpha, size, and ui-avatars.com rendering options as one-off overrides

avatar_url(name="Ada Lovelace", color="#dc2626")
# pick a specific color, skipping the palette

avatar_url(name="Ada Lovelace", alpha=1, background="#000")
# pin the background, let the text color rotate with the palette

avatar_url(name="Ada Lovelace", font_color="#fff")
# pin the text color, let the background rotate with the palette

avatar_url(name="Ada Lovelace", email="ada@example.com", format="png")
# force png or svg, note Gravatar errors for svg default images

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

avatar_url(name="Ada Lovelace", email="ada@example.com", source="secure.gravatar.com")
# use a custom Gravatar-compatible photo source

avatar_url(name="Ada Lovelace", region="eu")
# use the EU ui-avatars.com endpoint for generated initials

avatar_url(name="Ada Lovelace", host="avatars.example.com")
# use a custom or self-hosted UI Avatars endpoint

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

avatar_url(name="Ada Lovelace", format="webp", proxy="images.example.com")
# use a self-hosted wsrv.nl instance instead of the public api

Configuration

Reconfigure the shared avatars instance once, at startup, to change the palette for every call:

from ui_avatars import avatars

avatars.configure(colors=["#1d4ed8", "#b91c1c"], size=256, rounded=True)

Or build your own instance instead:

from ui_avatars import Avatars

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

The default palette is tailwind_colors's RAINBOW_500. You can swap the whole palette like so:

from tailwind_colors import TCH

avatars.configure(colors=TCH.RAINBOW_300)

For an independent background/text color instead of one tinted from the other, use a (background, text) tuple as a colors entry — alpha still applies to whichever background results:

avatars.configure(colors=[("#fee2e2", "#ef4444"), ("#ffedd5", "#f97316")])

Development

poetry install
poetry run pytest
poetry run ruff check .

License

MIT