Install & Compatibility
Where this runs
tested against v1.22.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.168s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Serializer
✓ from serpyco_rs import Serializer
The primary class for defining serializers for dataclasses.
dataclass
✓ from dataclasses import dataclass
Used to define the data structures that serpyco-rs serializes.
This example demonstrates how to define a dataclass, create a serializer for it, and then use the serializer to dump a dataclass instance to a dictionary, load a dictionary into a dataclass instance, and generate a JSON Schema for the defined structure.
import dataclasses
from serpyco_rs import Serializer
@dataclasses.dataclass
class User:
id: int
name: str
email: str
is_active: bool = True
# Create a serializer for the User dataclass
user_serializer = Serializer(User)
# Create a User instance
user_instance = User(id=1, name="Alice", email="alice@example.com")
# Serialize the dataclass instance to a dictionary
dumped_data = user_serializer.dump(user_instance)
print(f"Dumped data: {dumped_data}")
# Expected: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com', 'is_active': True}
# Load data from a dictionary into a dataclass instance
loaded_data = {'id': 2, 'name': 'Bob', 'email': 'bob@example.com', 'is_active': False}
user_from_dict = user_serializer.load(loaded_data)
print(f"Loaded instance: {user_from_dict}")
# Expected: User(id=2, name='Bob', email='bob@example.com', is_active=False)
# Generate JSON Schema for the dataclass
json_schema = user_serializer.json_schema()
print(f"JSON Schema: {json_schema}")
Debug
Known issues
breakingAs of v1.20.0, `Min` and `Max` validators are now inclusive by default. If your existing code or schemas relied on exclusive behavior without explicitly setting an `inclusive` flag, this change will alter validation logic.fixFor explicit control, use the `inclusive` flag (e.g., `Min(value, inclusive=False)` or `Max(value, inclusive=False)`) to restore exclusive behavior where needed.
affects: >=1.20.0
gotchaPrior to v1.17.1, boolean values (`true`/`false`) were incorrectly accepted as integers during validation. If you were implicitly relying on this behavior, validation might now fail for such inputs.fixEnsure inputs strictly adhere to integer types where integers are expected, and booleans where booleans are expected. Upgrade to v1.17.1 or newer for correct type validation.
affects: <1.17.1
gotchaFor JSON Schema generation, simple union types now correctly generate `anyOf` constructs (since v1.17.0) and integer fields explicitly include `"format": "int64"` (since v1.15.0). These changes improve JSON Schema compliance but might cause discrepancies for consumers expecting older schema formats.fixReview generated JSON schemas after upgrading to ensure compatibility with downstream schema consumers. Adjust expectations or tooling to accommodate the more compliant schema output.
affects: <1.17.0 (union types), <1.15.0 (int64 format)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'serpyco_rs'
The `serpyco-rs` library has not been installed in the current Python environment, or the environment is not active.
fixInstall the library using pip: `pip install serpyco-rs`
serpyco_rs.json.ValidationError
Input data does not conform to the type hints or validation rules defined in the dataclass fields, leading to a deserialization failure.
fixEnsure the input data strictly matches the dataclass's field types and any specified constraints (e.g., provide an integer for an `int` field, a valid string for a `str` field, etc.).
ValueError: time data '...' does not match format '%Y-%m-%dT%H:%M:%S.%fZ'
The input datetime string provided for a `datetime` field does not match the expected format, which by default for `serpyco-rs` is ISO 8601 with microseconds.
fixProvide datetime strings in the format `YYYY-MM-DDTHH:MM:SS.ffffffZ` (e.g., `2023-10-27T10:30:00.123456Z`), or initialize `serpyco_rs.Serializer` with a custom `datetime_format` matching your input.
Upgrade
Version history
1.22.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
No dependency data recorded yet.