Work with familiar Python data structures and type annotations. Mashumaro generates specialized encoders and decoders for them — no handwritten schemas or framework-specific models required.
- 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.
Mashumaro is used by projects of all kinds, both directly and through other packages. Explore a selection from both groups below.
Music Assistant · SimpleFold · Flytekit · Nesso · pySmartThings · Vunnel · ESPHome Device Builder · MySkoda · dbt-common · HomeWizard Energy · TrueConf Bot · pxblat
More projects and verification
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
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.
pip install mashumaroThe 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.
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 == eventNested 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.
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.
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.
| Area | Highlights |
|---|---|
| Models | Dataclasses and recursively nested standard-library and typing constructs |
| APIs | Mixins for dataclass models and reusable codecs for arbitrary supported type shapes |
| Outputs | Basic Python values, JSON via the standard library or orjson, YAML, TOML, and MessagePack |
| Customization | Field aliases, serialization strategies, custom and third-party types, dialects, hooks, discriminators, and omission rules |
| Schema generation | JSON Schema Draft 2020-12 and OpenAPI 3.1 |
The full compatibility matrix and format-specific representations are documented in Supported Types and Supported Formats.
- 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.
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.