Registry / serialization / dataclass-wizard

dataclass-wizard

JSON →
library1.0.0pypypi✓ verified 30d ago

Dataclass Wizard is a fast, lightweight, and pure Python serialization library for extending native Python dataclasses. It provides elegant tools for marshalling dataclass instances to and from JSON, Python dictionary objects, and environment variables, along with support for field properties with default values. The library is actively maintained, with frequent updates and a recently introduced opt-in v1 engine offering enhanced features and improved performance.

pip install dataclass-wizard
INSTALL
IMPORT
SIG · DATACLASS-WIZARD
D
dataclass-wizard
serializationpythonv1.0.0
Install
1.8s avg
Import
132ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.0.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
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.140s · 20.2MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.124s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DataclassWizard
✓ from dataclass_wizard import DataclassWizard
✗ from dataclass_wizard import JSONSerializable
While JSONSerializable is functionally equivalent, DataclassWizard is the new preferred base class for the v1 API as of v0.36.0+ and auto-applies the @dataclass decorator, reducing boilerplate.
JSONWizard
✓ from dataclass_wizard import JSONWizard
An alias for JSONSerializable, commonly used for JSON (de)serialization.
EnvWizard
✓ from dataclass_wizard import EnvWizard
Used for loading environment variables into dataclass schemas.
property_wizard
✓ from dataclass_wizard import property_wizard
Used as a metaclass to support field properties with default values in dataclasses.
json_field
✓ from dataclass_wizard import json_field
A helper function for configuring dataclass fields for JSON serialization, similar to `dataclasses.field`.

This quickstart demonstrates basic JSON serialization and deserialization using the `DataclassWizard` mixin, as well as loading configuration from environment variables using `EnvWizard`.

import os from dataclasses import dataclass from dataclass_wizard import DataclassWizard, EnvWizard # --- JSON Serialization/Deserialization --- @dataclass class User(DataclassWizard): id: int name: str email: str json_data = '{"id": 1, "name": "Ritvik", "email": "test@example.com"}' user = User.from_json(json_data) print(f"Deserialized User: {user!r}") # Expected: User(id=1, name='Ritvik', email='test@example.com') user_dict = user.to_dict() print(f"User to dict: {user_dict}") # Expected: {'id': 1, 'name': 'Ritvik', 'email': 'test@example.com'} # --- Environment Variable Loading --- os.environ['APP_NAME'] = 'MyEnvApp' os.environ['DEBUG_MODE'] = 'true' @dataclass class AppConfig(EnvWizard): app_name: str debug_mode: bool config = AppConfig.from_env() print(f"App Config: {config!r}") # Expected: AppConfig(app_name='MyEnvApp', debug_mode=True)
Debug
Known issues
breakingStarting with v1.0.0, the default key transformation for JSON serialization will change from camelCase (e.g., 'myField') to keeping keys as-is (e.g., 'my_field'). Users relying on automatic camelCase conversion should explicitly set `v1_key_case='camel'` in the inner `Meta` class or use `JSONPyWizard` if no transformation is desired.
fix
For existing code, either explicitly configure `v1_key_case='camel'` in the `Meta` class of your dataclasses, or update your JSON input/output to match the as-is key names. Alternatively, use `JSONPyWizard` for strict Pythonic (snake_case) key handling.
affects: >=1.0.0
deprecatedThe old 'nested path' functionality (prior to v0.35.0) for mapping deeply nested JSON keys to dataclass fields is deprecated and will no longer be maintained. It has been superseded by enhanced v1 opt-in features.
fix
Migrate to the new v1 opt-in features for mapping nested JSON paths, utilizing `KeyPath` or `path_field` in conjunction with `Annotated` types (e.g., `field_name: Annotated[str, KeyPath('data.items.value')]`).
affects: <0.35.0
gotchaWhen working with `Union` types that contain nested dataclasses, `dataclass-wizard` may raise `ParseError` if it cannot infer the correct type, especially in ambiguous cases.
fix
To resolve `ParseError` for `Union` types, explicitly define a `tag_key` and a unique `tag` within the inner `Meta` class of each dataclass participating in the `Union`. This provides clear discrimination for the parser.
affects: All versions
gotchaBy default, unknown or extraneous JSON keys encountered during deserialization (`from_dict` or `from_json`) are ignored, and a warning is emitted if debug mode is enabled.
fix
To enforce strict parsing and raise an `UnknownKeysError` (or `UnknownJSONKey` in older versions) when unknown keys are present, configure `v1_on_unknown_key='RAISE'` within the inner `Meta` class of your dataclass.
affects: All versions
gotchaOlder versions of `dataclass-wizard` (prior to fixes around v0.32.1 and subsequent v1 improvements) might encounter `ParseError` when attempting to parse types that include `typing.Any` when running on Python 3.11+.
fix
Ensure you are using a recent version of `dataclass-wizard` (0.32.1 or newer) for improved compatibility and correct parsing of `Any` types, particularly with Python 3.11 and later.
affects: <0.32.1 (especially with Python 3.11+)
gotchaThe `JSONSerializable` (and its alias `JSONWizard` or `DataclassWizard`) mixin class overrides the default `__str__` method to pretty-print the JSON representation of the object, which is useful for debugging but might not be desired for all use cases.
fix
If you prefer the default dataclass `__str__` behavior, you can disable the override by passing `str=False` when inheriting from the mixin, e.g., `class MyClass(DataclassWizard, str=False):`.
affects: All versions
Errors
Common errors & fixes
dataclass_wizard.errors.UnknownJSONKey: Unknown JSON key 'your_unmapped_key' in class 'YourDataclassName'
This error occurs when the JSON input contains a key that does not have a corresponding field defined in the dataclass being deserialized, and the `raise_on_unknown_json_key` setting is enabled.
fix
To fix this, either define the 'your_unmapped_key' field in your dataclass, or configure the `JSONWizard.Meta` class to ignore unknown keys or capture them using a `CatchAll` field.

Example to ignore unknown keys:
```python
from dataclasses import dataclass
from dataclass_wizard import JSONWizard

@dataclass
class MyData(JSONWizard):
    class _(JSONWizard.Meta):
        raise_on_unknown_json_key = False # Default behavior, but can be explicitly set
    field_a: str
    field_b: int

# Or to capture them:
from dataclass_wizard.enums import CatchAll
@dataclass
class MyDataWithCatchAll(JSONWizard):
    field_a: str
    unknown_fields: CatchAll
```
dataclass_wizard.errors.ParseError: Failure parsing field None in class None. Expected a type Any, got NoneType. value: None error: Provided type is not currently supported. unsupported_type: typing.Any
This specific error was a known bug in `dataclass-wizard` when used with Python 3.11, related to how `typing.Any` was handled during type introspection.
fix
This issue has been resolved in newer versions of `dataclass-wizard`. Upgrade the library to the latest version (0.32.1 or higher is mentioned as a fix for a related bug in 0.32.0, so generally upgrading is the solution).

```bash
pip install --upgrade dataclass-wizard
```
dataclass_wizard.errors.RecursiveClassError: Failure parsing class `YourRecursiveClass`. Consider updating the Meta config to enable the `recursive_classes` flag.
This error occurs when attempting to deserialize a dataclass that has self-referential or cyclic (recursive) type hints without explicitly enabling the `recursive_classes` flag in the `Meta` configuration.
fix
Enable the `recursive_classes` flag in the `Meta` configuration for your dataclass, or bind it using `LoadMeta`.

```python
from dataclasses import dataclass
from dataclass_wizard import JSONWizard, LoadMeta

@dataclass
class Node:
    name: str
    children: list['Node']

# Method 1: Using an inner Meta class
@dataclass
class MyTree(JSONWizard):
    class _(JSONWizard.Meta):
        recursive_classes = True
    root: Node

# Method 2: Using LoadMeta.bind_to
LoadMeta(recursive_classes=True).bind_to(Node)
```
dataclass_wizard.errors.ParseError: Cannot determine which class to deserialize to for field 'your_union_field'. No tag key 'type' found in input.
This `ParseError` typically occurs when a dataclass field is annotated with a `Union` of other dataclasses (e.g., `Union[ClassA, ClassB]`), and the library cannot automatically infer which specific class to use for deserialization from the input data. This often happens if a `tag_key` is not specified to disambiguate.
fix
Define a `tag_key` in the `JSONWizard.Meta` configuration and ensure your JSON input includes this tag to help `dataclass-wizard` determine the correct class for deserialization within the Union type.

```python
from dataclasses import dataclass
from typing import Union
from dataclass_wizard import JSONWizard

@dataclass
class Cat:
    name: str
    type: str = 'cat'

@dataclass
class Dog:
    name: str
    type: str = 'dog'

@dataclass
class PetContainer(JSONWizard):
    class _(JSONWizard.Meta):
        # 'type' field in the JSON will determine which class to use
        tag_key = 'type'
        auto_assign_tags = True # Automatically adds the 'type' field on serialization
    pet: Union[Cat, Dog]

# Example JSON: {'pet': {'type': 'cat', 'name': 'Whiskers'}}
```
Upgrade
Version history
1.0.0latest on PyPI · released Jul 3, 2026
Audit
Dependencies
typing-extensionsoptionalBackports new typing features for Python 3.10 and earlier versions. Automatically included if needed.
Agent activity
65 hits · last 30 days
node
44
Bingbot
20
Resources
dataclass-wizard — pip install dataclass-wizard · libregistry