msgspec

Warnings

• breaking msgspec 0.19.0 dropped support for Python 3.8. Users on Python 3.8 or older must upgrade their Python version or stay on msgspec < 0.19.0.
  Fix: Upgrade Python to 3.9+.
• breaking In msgspec 0.19.0, the `encode_into` method (an advanced API) now expands the buffer if it's smaller than the offset, which is a breaking change for specific buffer management use cases.
  Fix: Review usage of `Encoder.encode_into` and ensure buffer management aligns with the new behavior, potentially pre-allocating larger buffers or handling re-allocation.
• deprecated The `from_builtins` method was removed in msgspec 0.19.0. Users should now use `msgspec.convert` for similar functionality.
  Fix: Replace calls to `from_builtins` with `msgspec.convert`.
• gotcha When using `msgspec.msgpack` to decode into `memoryview` objects, the original input message buffer will be kept in memory as long as the `memoryview` is alive. This can lead to unexpectedly high memory usage if not carefully managed, especially with large messages or long-lived `memoryview` instances.
  Fix: Only use `memoryview` for zero-copy scenarios when strict performance is needed and memory lifecycle is precisely controlled. For most cases, prefer `bytes` or `bytearray` to ensure the input buffer can be garbage collected.
• gotcha Mutable default values (e.g., `list`, `set`, `dict`) on `msgspec.Struct` fields will be shared across all instances if not defined using `msgspec.field(default_factory=...)`. This is a common Python pitfall.
  Fix: Always use `msgspec.field(default_factory=my_callable)` for mutable default values, where `my_callable` is a zero-argument function that returns a new mutable object (e.g., `list`, `set`, `dict`).
• gotcha The `msgspec.structs.fields()` function can be significantly slower (up to 20x) than `dataclasses.fields()` because it re-inspects type annotations on every invocation. Avoid frequent calls to `msgspec.structs.fields()` in performance-critical loops.
  Fix: Cache the result of `msgspec.structs.fields()` if it's called repeatedly for the same `Struct` type, or redesign code to minimize its usage in hot paths.
• breaking In msgspec 0.7.0, the `nogc` struct option was renamed to `gc`. To disable garbage collection for a Struct instance, you must now specify `gc=False` instead of `nogc=True`.
  Fix: Update `Struct` definitions and instantiation calls from `nogc=True` to `gc=False`.

Install

• pip install msgspec Basic Install
• pip install msgspec[yaml,toml] Install with YAML and TOML support

Imports

• Struct

  from msgspec import Struct

• field

  from msgspec import field

• json

  import msgspec.json

  Provides `encode`, `decode`, `Encoder`, `Decoder` for JSON.
• msgpack

  import msgspec.msgpack

  Provides `encode`, `decode`, `Encoder`, `Decoder` for MessagePack.
• yaml

  import msgspec.yaml

  Provides `encode`, `decode`, `Encoder`, `Decoder` for YAML (requires PyYAML).
• toml

  import msgspec.toml

  Provides `encode`, `decode`, `Encoder`, `Decoder` for TOML (requires tomli-w).

Quickstart

Defines a simple `User` struct, encodes it to JSON, and then decodes it back. It also demonstrates how `msgspec` handles type validation errors during decoding. Uses `msgspec.field(default_factory=set)` for mutable default values to prevent common Python footguns.

import msgspec

class User(msgspec.Struct):
    name: str
    age: int
    email: str | None = None
    groups: set[str] = msgspec.field(default_factory=set)

alice = User(name="alice", age=30, groups={"admin", "dev"})
print(f"Original User: {alice}")

# Encode to JSON
json_data = msgspec.json.encode(alice)
print(f"Encoded JSON: {json_data.decode()}")

# Decode from JSON
decoded_alice = msgspec.json.decode(json_data, type=User)
print(f"Decoded User: {decoded_alice}")

# Example of validation error
try:
    msgspec.json.decode(b'{"name":"bob","age":"25"}', type=User)
except msgspec.ValidationError as e:
    print(f"Validation Error: {e}")