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

Name	Default	Description
alpha	0.2	Background opacity (0 to 1)
background		Pin the background color
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")

Development

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

License

MIT