Why mashumaro?

• Standard Python first. Keep ordinary dataclasses, collections, and type annotations; add a lightweight mixin only when you want methods on a model.
• Fast by design. Mashumaro generates conversion code for the exact type shape instead of repeatedly inspecting it at runtime.
• Broad typing support. Generics, unions, Annotated, Literal, TypedDict, NamedTuple, recursive models, and much more work recursively.
• Two simple APIs. Add methods to a dataclass with a mixin, or create a reusable codec for any supported root type such as list[Event].
• Use the format you already have. Convert to dictionaries, JSON, orjson, YAML, TOML, and MessagePack, and generate JSON Schema when you need it.

Mashumaro focuses on typed data conversion and serialization. It deliberately does not try to be a business-rule validation framework or replace your model layer.

Used across the Python ecosystem

Mashumaro is used by projects of all kinds, both directly and through other packages. Explore a selection from both groups below.

Featured projects using mashumaro directly

                                

_{Music Assistant · SimpleFold · Flytekit · Nesso · pySmartThings · Vunnel · ESPHome Device Builder · MySkoda · dbt-common · HomeWizard Energy · TrueConf Bot · pxblat}

More projects and verification

More projects using mashumaro directly

Data and developer tools
Aligned · dbt-autofix · Flyte SDK

Science and machine learning
Allophant · Boltz · Patchr

Devices and web APIs
Bring API · Open-Meteo · pylamarzocco · PyMammotion · python-kasa · pyvesync · TikTokLive

_{and about 100 more projects}

Featured projects using mashumaro indirectly

                                

_{Prefect · dlt · LedFx · Dune Spellbook · sqruff · ZHA Device Handlers · dbt MCP · Recce · Dagster Open Platform · Databricks DQX · dbt-sqlserver · dbt-fabric}

Data and dbt tooling
airflow-dbt-python · dbt-metabase · dbt-osmosis · dbt-score · dbterd

Connected-device integrations
Alexa Media Player · Better Thermostat · Hilo · Home Assistant MySkoda · Midea AC LAN · Powercalc · Spook · Toyota Connected Services

_{and about 500 more projects}

Selection and verification

The September 30, 2026 snapshot paginated all 118 pages of the repository view of the GitHub dependency graph and cross-referenced its package view. It found 939 repositories with at least two stars; after excluding 36 forks, 903 remained. After verification, 125 had direct evidence in conventional dependency files and 11 more in unusual locations. Another 507 had only effective transitive evidence, while 259 could not be resolved.

Only exactly named dependency files in the repository root or directly under src/ are treated as conventional locations. GitHub's relationship is accepted for declaration files such as pyproject.toml, setup.py, setup.cfg, and requirements.in. Lockfiles and requirements snapshots that GitHub labels direct receive an additional content check. If another locked package depends on mashumaro and there is no edge from the local project, the relationship is reclassified as transitive. A requirements.txt entry is direct only when its own # via provenance points to an input declaration; freeze-style snapshots without per-entry provenance remain unresolved unless other evidence is conclusive. When a conventional dependency file has no recognizable GitHub relationship label, its contents are checked directly; an explicit declaration can still confirm direct use, while unreadable or ambiguous evidence fails closed as unresolved.

When GitHub's package view identifies a published package, its PyPI requires_dist metadata provides a second directness check. An explicit mashumaro requirement confirms direct use; a conclusive absence rejects the GitHub-direct result. Network and metadata failures are treated as inconclusive. Every project shown in the indirect usage sample therefore has only effective transitive relationships; unresolved repositories are counted but not featured.

For the gallery, each candidate was reviewed in context. A project was kept when mashumaro belongs to its maintained application, library, or clearly named product component. Repositories where the match came only from a demo, benchmark, test fixture, vendored copy, or generated dependency set were left out. This avoids presenting incidental development environments as product adoption.

Images are limited to organization marks from the reviewed repository data; projects under personal accounts are listed by name instead. Dependency data, repository activity, and ownership can change between snapshots. Logos belong to their respective projects, and inclusion does not imply endorsement.

Installation

pip install mashumaro

The current release supports Python 3.10–3.15. Install optional formats only when you need them:

pip install "mashumaro[orjson,yaml,toml,msgpack]"

See Migration and Compatibility for the last releases supporting older Python versions.

Quick start

Add serialization methods to a dataclass

from dataclasses import dataclass
from datetime import datetime

from mashumaro.mixins.json import DataClassJSONMixin


@dataclass
class Event(DataClassJSONMixin):
    name: str
    starts_at: datetime
    speakers: list[str]


event = Event(
    name="PyCon",
    starts_at=datetime(2026, 5, 13, 9, 0),
    speakers=["Alice", "Bob"],
)

payload = event.to_json()
restored = Event.from_json(payload)

assert restored == event

Nested dataclasses remain plain dataclasses; only the root model needs the mixin. Format-specific mixins for orjson, YAML, TOML, and MessagePack expose the same style of API.

Build a codec for any supported type shape

from mashumaro.codecs.json import JSONDecoder, JSONEncoder

encoder = JSONEncoder(list[Event])
decoder = JSONDecoder(list[Event])

payload = encoder.encode([event])
restored = decoder.decode(payload)

assert restored == [event]

Construct codecs once and reuse them when performance matters. A codec root can be a dataclass, collection, TypedDict, union, scalar, or another supported type shape.

Performance

Mashumaro generates specialized conversion functions once, then reuses them without repeatedly walking fields and annotations. The repository benchmark uses pyperf and a nested GitHub Issue model.

The results below were recorded on macOS 27.0.1, an Apple M3 Max, and Python 3.14.6. Lower is better; the charts use a logarithmic scale.

Benchmarks are workload- and configuration-dependent. Compare equivalent validation, conversion, and output semantics before drawing conclusions. See the performance guide for methodology and run ./benchmark/run.sh to reproduce the benchmark locally.

At a glance

The full compatibility matrix and format-specific representations are documented in Supported Types and Supported Formats.

Where to go next

• New to mashumaro? Start with Getting Started.
• Checking compatibility? See Supported Types and Supported Formats.
• Customizing representations? Read about Field Options, Config Options, SerializationStrategy, SerializableType, and Dialects.
• Looking for real-world patterns? Browse Practical Recipes.
• Integrating with tooling? See JSON Schema and the API Reference.
• Something went wrong? See Errors and Troubleshooting.

Browse the complete documentation for all chapters.

Contributing

Bug reports and pull requests are welcome. Please read the contributing guide and report security issues according to the security policy.

Mashumaro is distributed under the Apache License 2.0.