index.rst

msgspec

msgspec is a fast serialization and validation library, with builtin support for JSON, MessagePack, YAML, and TOML. It features:

• 🚀 High performance encoders/decoders for common protocols. The JSON and MessagePack implementations regularly :doc:`benchmark <benchmarks>` as the fastest options for Python.
• 🎉 Support for a wide variety of Python types. Additional types may be supported through :doc:`extensions <extending>`.
• 🔍 Zero-cost schema validation using familiar Python type annotations. In :doc:`benchmarks <benchmarks>` msgspec decodes and validates JSON faster than orjson can decode it alone.
• ✨ A speedy Struct type for representing structured data. If you already use dataclasses or attrs, :doc:`structs` should feel familiar. However, they're :ref:`5-60x <struct-benchmark>` faster for common operations.

All of this is included in a :ref:`lightweight library <benchmark-library-size>` with no required dependencies.

---

msgspec may be used for serialization alone, as a faster JSON or MessagePack library. For the greatest benefit though, we recommend using msgspec to handle the full serialization & validation workflow:

Define your message schemas using standard Python type annotations.

>>> import msgspec

>>> class User(msgspec.Struct):
...     """A new type describing a User"""
...     name: str
...     groups: set[str] = set()
...     email: str | None = None

Encode messages as JSON, or one of the many other supported protocols.

>>> alice = User("alice", groups={"admin", "engineering"})

>>> alice
User(name='alice', groups={"admin", "engineering"}, email=None)

>>> msg = msgspec.json.encode(alice)

>>> msg
b'{"name":"alice","groups":["admin","engineering"],"email":null}'

Decode messages back into Python objects, with optional schema validation.

>>> msgspec.json.decode(msg, type=User)
User(name='alice', groups={"admin", "engineering"}, email=None)

>>> msgspec.json.decode(b'{"name":"bob","groups":[123]}', type=User)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
msgspec.ValidationError: Expected `str`, got `int` - at `$.groups[0]`

msgspec is designed to be as performant as possible, while retaining some of the nicities of validation libraries like pydantic. For supported types, encoding/decoding a message with msgspec can be :doc:`~10-80x faster than alternative libraries <benchmarks>`.

Highlights

• msgspec is fast. It :doc:`benchmarks <benchmarks>` as the fastest serialization library for Python, outperforming all other JSON/MessagePack libraries compared.
• msgspec is friendly. Through use of Python's type annotations, messages are :ref:`validated <typed-decoding>` during deserialization in a declarative way. msgspec also works well with other type-checking tooling like mypy and pyright, providing excellent editor integration.
• msgspec is flexible. It natively supports a :doc:`wide range of Python builtin types <supported-types>`. Support for additional types can also be added through :doc:`extensions <extending>`.
• msgspec is lightweight. It has no required dependencies, and the binary size is :ref:`a fraction of that of comparable libraries <benchmark-library-size>`.
• msgspec is correct. The encoders/decoders implemented are strictly compliant with their respective specifications, providing stronger guarantees of compatibility with other systems.

Used By

msgspec is used by many organizations and open source projects, here we highlight a few:

.. grid:: 2 2 4 4

    .. grid-item-card:: NautilusTrader
        :link: https://nautilustrader.io/

        .. image:: _static/nautilus-trader.png

    .. grid-item-card:: Litestar
        :link: https://litestar.dev/

        .. image:: _static/litestar.png

    .. grid-item-card:: Sanic
        :link: https://sanic.dev/en/

        .. image:: _static/sanic.png

    .. grid-item-card:: Mosec
        :link: https://mosecorg.github.io/mosec/

        .. image:: _static/mosec.png

    .. grid-item-card:: Pioreactor
        :link: https://pioreactor.com/

        .. image:: _static/pioreactor.png

    .. grid-item-card:: Zero
        :link: https://github.com/Ananto30/zero

        .. image:: _static/zero.png

    .. grid-item-card:: anywidget
        :link: https://anywidget.dev/

        .. image:: _static/anywidget.png

    .. grid-item-card:: esmerald
        :link: https://esmerald.dev/

        .. image:: _static/esmerald.png

    .. grid-item-card:: Faststream
        :link: https://faststream.ag2.ai/

        .. image:: _static/faststream.png

.. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Overview

    why.rst
    install.rst
    benchmarks.rst

.. toctree::
    :hidden:
    :maxdepth: 2
    :caption: User Guide

    usage.rst
    supported-types.rst
    structs.rst
    constraints.rst
    converters.rst
    jsonschema.rst
    schema-evolution.rst

.. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Advanced

    extending.rst
    inspect.rst
    perf-tips.rst

.. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Reference

    api.rst
    examples/index.rst
    changelog.rst