dicebear 4.0.0b2

Caution

⚠️ This is a beta release. The API may still change before the final v4.0.0.

What's new

This release is a complete overhaul of the dicebear package. The old package was an HTTP API wrapper — every avatar required a network call to api.dicebear.com. v4 generates avatars entirely locally, in-process, with no network dependency whatsoever.

Local rendering engine

Avatars are now generated by a full Python implementation of the DiceBear Core rendering engine, producing byte-identical SVGs to the official JavaScript and PHP implementations for the same seed and style. The engine is verified against DiceBear's own language-neutral parity test suite.

Better developer experience

Style classes are fully typed with nested enums, giving you IDE autocomplete and type-safe avatar configuration:

from dicebear import Avatar, Options, Color
from dicebear.styles import Avataaars

av = Avatar(
    Avataaars(eyes=Avataaars.Eyes.WINK, hair=Avataaars.Hair.SHORT_HAIR_SHORT_FLAT),
    seed="john doe",
    options=Options(flip=True, backgroundColor=Color("00ddd0")),
)

print(av.svg)  # generated locally, no network

Typing Avataaars. in your IDE now shows every available component. Typing Avataaars.Eyes. shows every valid variant. Typos are caught at type-check time instead of silently producing wrong output.

Style definitions

Avatar style definitions are provided by the official dicebear-styles PyPI package, maintained by the DiceBear project. This means style updates ship independently of this package and are managed like any other dependency.

Breaking changes

v4 is not compatible with v3 in any way. The entire API has been redesigned.

v3	v4
DAvatar(style=DStyle.avataaars, seed="...")	Avatar(Avataaars(), seed="...")
DOptions(backgroundColor=DColor("ff0000"))	Options(backgroundColor=Color("ff0000"))
av.url_svg	av.svg
av.save(file_format=DFormat.svg)	av.save("avatar.svg", format=Format.SVG)
bulk_create(style=DStyle.random(), amount=10)	Avatar.bulk_create(Avataaars, amount=10)

Installation

pip install dicebear==4.0.0b2

# For PNG/JPG/WEBP output (optional):
pip install "dicebear[pillow]==4.0.0b2"

Supported formats

Format	Requires
SVG	nothing extra
PNG	pip install dicebear[pillow]
JPG / JPEG	pip install dicebear[pillow]
WEBP	pip install dicebear[pillow]

Feedback

This is a beta, please open an issue if you run into anything unexpected. Even though there are many tests to catch bugs before being published, bugs can be sneaky and get through sometimes.