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.

dicebear 4.0.0b1

This beta introduces a fully typed, IDE-friendly API for style customisation, built on the same JSON-driven architecture DiceBear v10 uses internally. All existing code continues to work unchanged.

---

What's new

Typed style classes

Each avatar style now has its own Python dataclass with typed, documented fields. No more passing an untyped custom dict and guessing option names — your IDE will autocomplete them, and invalid usage is caught at construction time before any HTTP call is made.

from dicebear import DAvatar, DOptions, DColor
from dicebear.styles.adventurer import Adventurer

# Default avatar — pass the class directly
avatar = DAvatar(Adventurer, "john doe")

# Customised avatar — pass an instance
avatar = DAvatar(
    Adventurer(eyes=["variant01"], hair=["long01"], hairColor=DColor("b9a05f")),
    "john doe",
    options=DOptions(flip=True),
)

Without type-hinting

When you need to step outside the typed system (e.g. to pass an undocumented option), convert a style instance to a plain dict and extend it:

custom = {**Adventurer(eyes=["variant01"]).to_dict(), "someParam": "value"}
avatar = DAvatar("adventurer", "john doe", custom=custom)

JSON-driven code generation

Style classes are generated from the official dicebear/styles (https://github.com/dicebear/styles) JSON definitions — not hand-written. A workflow_dispatch CI action fetches the latest schemas and regenerates all files, keeping the library in sync with upstream automatically.

6 new styles

Styles now match the full dicebear/styles repo (37 total). New additions: Disco, Glyphs, Initial Face, Shape Grid, Stripes, Triangles.

---

Backwards compatibility

All v3.x code continues to work without any changes:

# This still works exactly as before
DAvatar(DStyle.adventurer, "john doe", custom={"eyes": "variant01"})

---

Breaking changes

None. This release is purely additive.

---

Upgrading

pip install dicebear==4.0.0b1

---

Caution

Beta notice — the typed style classes API is new. Field names are derived directly from the upstream JSON definitions and may shift if DiceBear updates their schemas before 4.0.0 stable. Python classes are automatically generated from these JSON definitions, so they may be inaccurate during this beta phase.

Please report any issues.

dicebear 3.9.5

Check out https://dicebear.vhjan.me/ for the documentation.

If you encounter any errors or bugs, please open an issue!

Nothing has been changed in the package itself, only the way of publishing the package to Pypi has been updated.

dicebear 3.9.5a3

Pre-release alpha to validate the new PyPI publishing pipeline. No code changes, this release exists solely to test the updated pyproject.toml structure and the new Trusted Publisher workflow.

dicebear 3.9.5a2

Pre-release alpha to validate the new PyPI publishing pipeline. No code changes, this release exists solely to test the updated pyproject.toml structure and the new Trusted Publisher workflow.

dicebear 3.9.5a1

Pre-release alpha to validate the new PyPI publishing pipeline. No code changes, this release exists solely to test the updated pyproject.toml structure and the new Trusted Publisher workflow.

dicebear 3.9.4

Check out https://dicebear.vhjan.me/ for the documentation.

If you encounter any errors or bugs, please open an issue!

Added

• New style toon-head

dicebear 3.9.3

Check out https://dicebear.vhjan.me/ for the documentation.

If you encounter any errors or bugs, please open an issue!

Changed

• DAvatar now has a new parameter save_to_cache (default True) to choose whether to save
  avatars to the cache or not. Caching them will make it easier and quicker to access
  the avatars again, and will reduce outgoing API calls.

dicebear 3.9.2

Check out https://dicebear.vhjan.me/ for the documentation.

If you encounter any errors or bugs, please open an issue!

Back-end

The back-end has been reworked a lot to make the whole framework faster and more efficient.
The package now also supports caching to avoid making redundant requests.

A safer way of making requests to avoid hanging indefinitely or raising generic/unnecessary errors.

dicebear 2.9.2

Check out https://dicebear.vhjan.me/ for the documentation.

If you encounter any errors or bugs, please open an issue!

Added

• New styles dylan and glass
• New modern alternative file formats webp and avif (use these instead of png or jp(e)g)