High-performance serialization without replacing your data model
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.
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
| 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.
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.
1 maintainer
Metadata
1 maintainer
Release files for mashumaro 3.23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mashumaro-3.23.tar.gz | 141.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mashumaro-3.23-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 220.5 kB
Release files / mashumaro-3.23.tar.gz
| Download URL | mashumaro-3.23.tar.gz |
|---|---|
| Size | 141.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ed69d5bc548c76efbb5286cc0e541a6b8796e621385f986e25b750364011abf5
|
|
BLAKE2b-256 checksum How to use checksums |
09186383ce957a0551d8704936ffef1ecf0b0c620543999a44f9adf6c5f30888
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / mashumaro-3.23-py3-none-any.whl
| Download URL | mashumaro-3.23-py3-none-any.whl |
|---|---|
| Size | 78.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a671279ce93119d41c54adcd767753ae68adb32b9473de2f9d5d1720d2376231
|
|
BLAKE2b-256 checksum How to use checksums |
4eeb2c5e2b0df54c9c979d45bfa4820687ab24797fe1ad42d4fdfc0c8ece59f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency log
