DiceBear: Same Name, Byte-Identical Avatars Across All Platforms

Introduction

When users register without uploading an avatar, applications typically show a generic placeholder or use an external avatar service. DiceBear offers a different approach: an open-source library that generates an SVG avatar from any string (username, email, user ID) directly inside the project, with no dependency on an online service.

Cross-Platform Consistency Verification

The author tested DiceBear 10.7.0 (61 styles) on a Mac with Node 24 across five environments: browser, Node.js, Python, CLI, and the official API. Using the seed "技术洋" and the lorelei style, all four generated SVG files were byte-for-byte identical, confirmed by SHA-256 hashes:

5d0e5e3668c05b6d93540d3206669c657a1facae92aaff8320d497bfba28961e  api.svg
5d0e5e3668c05b6d93540d3206669c657a1facae92aaff8320d497bfba28961e  cli.svg
5d0e5e3668c05b6d93540d3206669c657a1facae92aaff8320d497bfba28961e  js.svg
5d0e5e3668c05b6d93540d3206669c657a1facae92aaff8320d497bfba28961e  python.svg

The same result held when running the JavaScript directly in Chrome. The author also generated all 61 styles with Python and compared each to the Node output; every pair matched exactly. The library's documentation states that each language implementation must pass a shared test suite ensuring byte-identical output to the Node reference.

Node.js Usage

Install the core package and the styles collection: npm install @dicebear/core @dicebear/styles Create an ESM module ( avatar.js) with "type": "module" in package.json:

import { writeFileSync } from 'node:fs';
import { Avatar, Style } from '@dicebear/core';
import lorelei from '@dicebear/styles/lorelei.json' with { type: 'json' };

const avatar = new Avatar(new Style(lorelei), { seed: '技术洋', size: 128 });

writeFileSync('avatar.svg', avatar.toString());
console.log(avatar.toDataUri().slice(0, 60));

The seed is the input string; lorelei is the style name (swap by importing a different JSON such as bottts.json or pixel-art.json). toString() returns the SVG text; toDataUri() returns a data: URI usable directly in an

<img>

src

. Generating 1,000 avatars sequentially took under 0.1 seconds. Options like backgroundColor (hex without #) and borderRadius (50 for a circle) customize the output.

Python Usage

Install the Python packages: pip install dicebear-core dicebear-styles Load the style JSON via importlib.resources and create the avatar:

import json
from importlib.resources import files
from dicebear import Avatar, Style

lorelei = json.loads(files("dicebear_styles").joinpath("lorelei.json").read_text("utf-8"))
avatar = Avatar(Style(lorelei), {"seed": "技术洋", "size": 128})

with open("avatar-py.svg", "w", encoding="utf-8") as f:
    f.write(avatar.to_string())

The API mirrors the Node version ( to_string() instead of toString()).

CLI and Official API

Without writing code, the CLI generates avatars in one command (first run downloads the package):

npx dicebear lorelei ./avatars --seed 技术洋 --size 128

The official API endpoint is accessible in China:

https://api.dicebear.com/10.x/lorelei/svg?seed=技术洋&size=128

Why the Same Seed Always Produces the Same Image

Each avatar is composed of multiple parts (hair, eyes, mouth, colors). For every part, the library hashes the string " seed:partName " to a number between 0 and 1, then selects a candidate based on that number. Because the seed is unchanged, every part selection is deterministic, independent of execution order, machine, or language. Changing a single character in the seed (e.g., Felix vs felix) yields a completely different avatar. Using a stable user ID as the seed keeps the avatar constant across name changes.

Collision Analysis: Different Names Can Yield the Same Avatar

The combination space is finite, so collisions occur. The author generated avatars for user0 through user9999 (10,000 names) across all 61 styles and counted unique images:

Character-based styles ( avataaars, notionists, pixel-art) produced 10,000 distinct images; lorelei and adventurer had only a few duplicates.

Emoji/icon styles collided heavily: fun-emoji yielded ~1,300 unique images; glyphs only ~200.

The initials style draws only the first letters (all US for user0 – user9999), varying only background color.

Styles suffixed -neutral omit hair and clothing, reducing part variety and increasing collisions.

Therefore, avatars are suitable for visual recognition but not as unique identifiers. For large user bases where collisions matter, character-rich styles are recommended. The test used sequential usernames; real-world distributions may differ.

Avatars need not be stored; store the name instead. The same name generates the exact same image in the browser, backend, or CLI.