GitHub - shpaker/tiny-userpic: An oversimplified GitHub-like userpic generation Python library in a single small file

2 min read Original article ↗

Github-like Userpic (Avatar) Generator

Oversimplified Github-like userpic (avatar) generator.

Ruff PyPI PyPI

Features

  • Generate unique avatars from text input (email, username, etc.)
  • Create both PIL Image and SVG outputs
  • Customizable size, colors, and padding
  • Deterministic output (same input always produces the same avatar)

Installation

Usage

The library provides several ways to generate avatars:

1. Random Generation (Non-deterministic)

Generate a unique random avatar each time.

from tiny_userpic import make_userpic_image

# Generate random avatar
random_image = make_userpic_image(
    size=(7, 5),
    image_size=(300, 300),
    background="white",
    foreground="black"
)
random_image.save("random_avatar.png")

2. With Custom Seed (Deterministic)

Generate an avatar with a specific seed for reproducible results.

from tiny_userpic import make_userpic_image

# Generate avatar with specific seed
seeded_image = make_userpic_image(
    size=(7, 5),
    image_size=(300, 300),
    background="white",
    foreground="black",
    seed=42  # Any integer value will work as seed
)
seeded_image.save("seeded_avatar.png")

3. From Text Input (Deterministic)

Generate an avatar from any text input (email, username, etc.). The same input will always produce the same avatar.

from tiny_userpic import make_userpic_image_from_string, make_userpic_svg_from_string

# Generate avatar from email
email = "user@example.com"

# As PNG image
image = make_userpic_image_from_string(
    text=email,           # Input text to generate avatar from
    size=(7, 5),         # Pattern size (width, height)
    image_size=(300, 300), # Output image size in pixels
    background="white",   # Background color (can be color name, hex or RGB tuple)
    foreground="black"    # Foreground color (can be color name, hex or RGB tuple)
)
image.save("avatar.png")

# As SVG
svg = make_userpic_svg_from_string(
    text=email,
    size=(7, 5),
    image_size=(300, 300),
    background="white",
    foreground="black"
)
with open("avatar.svg", "w") as f:
    f.write(svg)

Common Parameters

All generation methods share these parameters:

  • size: Tuple of (width, height) for the pattern size
  • image_size: Tuple of (width, height) for the output image size in pixels
  • background: Background color (can be color name, hex or RGB tuple)
  • foreground: Foreground color (can be color name, hex or RGB tuple)
  • padding: Optional padding around the pattern (default: (20, 20))
  • mode: Image mode for PNG output (default: 'RGB', can be 'RGBA' for transparency)

Examples

Basic (from string)

Basic example

Colored

Colored example

Transparent

Transparent example

Small

Small example

Large

Large example

Random (non-deterministic)

Random example

Seeded (deterministic)

Seeded example