Getting started¶

Installation¶

Install pyserde from PyPI. pyserde requires Python>=3.10.

If you want faster JSON handling, you can also install orjson and use the orjson extra for optional acceleration.

pip install pyserde

If you're using uv, run this command.

uv add pyserde

Additional data formats besides JSON and Pickle need additional dependencies installed. Install msgpack, toml or yaml extras to work with the appropriate data formats; you can skip formats that you don't plan to use. For example, if you want to use Toml and YAML:

pip install "pyserde[toml,yaml]"

With uv

uv add pyserde --extra toml --extra yaml

Or all at once:

pip install "pyserde[all]"

With uv

uv add pyserde --extra all

Here are the available extras:

all: Install msgpack, toml, yaml, numpy, orjson, and sqlalchemy extras
msgpack: Install msgpack
toml: Install tomli and tomli-w
yaml: Install pyyaml
numpy: Install numpy
orjson: Install orjson
sqlalchemy: Install sqlalchemy

Note

tomllib is used for python 3.11 onwards

Note

Extras enable additional formats and types, but you can mix them as needed. For example, install only toml and yaml if you do not need MsgPack or numpy.

Define your first pyserde class¶

Define your class with pyserde's @serde decorators. Be careful that module name is serde, not pyserde. pyserde heavily depends on the standard library's dataclasses module. If you are new to dataclass, I would recommend to read dataclasses documentation first.

from serde import serde

@serde
class Foo:
    i: int
    s: str
    f: float
    b: bool

pyserde generates methods necessary for (de)serialization by @serde when a class is loaded into python interpreter. The code generation occurs only once and there is no overhead when you use the class. Now your class is serializable and deserializable in all the data formats supported by pyserde.

Note

If you need only either serialization or deserialization functionality, you can use @serialize or @deserialize instead of @serde decorator.

e.g. If you do only serialization, you can use @serialize decorator. But calling deserialize API e.g. from_json for Foo will raise an error.

from serde import serialize

@serialize
class Foo:
    i: int
    s: str
    f: float
    b: bool

PEP585 and PEP604¶

PEP585 style annotations and the PEP604 union operator are supported for python>=3.10. With PEP585 and PEP604, you can write a pyserde class pretty neatly.

@serde
class Foo:
    a: int
    b: list[str]
    c: tuple[int, float, str, bool]
    d: dict[str, list[tuple[str, int]]]
    e: str | None

Use pyserde class¶

Next, import pyserde (de)serialize APIs. For JSON:

from serde.json import from_json, to_json

Use to_json to serialize the object into JSON.

f = Foo(i=10, s='foo', f=100.0, b=True)
print(to_json(f))

Pass Foo class and JSON string in from_json to deserialize JSON into the object.

s = '{"i": 10, "s": "foo", "f": 100.0, "b": true}'
print(from_json(Foo, s))

You can also serialize to a Python dict when you need to manipulate data before writing it to a file or sending it over the network.

from serde import to_dict, from_dict

payload = to_dict(f)
# e.g. add a field before sending
payload["source"] = "cli"
print(from_dict(Foo, payload))

That's it! pyserde offers many more features. If you're interested, please read the rest of the documentation.

Note

If you plan to use YAML, TOML, or MsgPack, remember to install the matching extras listed above.

Which type checker should I use?

pyserde depends on PEP681 dataclass_transform. mypy does not fully support dataclass_transform as of Jan. 2024. My personal recommendation is pyright.