# dataclass-wizard

> A wizard-like JSON serialization library for Python dataclasses

- **URL**: https://www.freshcrate.ai/projects/dataclass-wizard
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `main@2026-06-01` (2026-06-01)
- **License**: non-standard
- **Source**: https://github.com/rnag/dataclass-wizard/issues
- **Homepage**: https://pypi.org/project/dataclass-wizard/
- **Language**: Python
- **GitHub**: 240 stars, 33 forks
- **Registry**: pypi (`dataclass-wizard`)
- **Tags**: `dataclass`, `dataclasses`, `deserialization`, `json`, `pypi`, `serialization`, `type`, `wizard`

## Description

.. image:: https://raw.githubusercontent.com/rnag/dataclass-wizard/main/images/logo.png
   :alt: Dataclass Wizard logo
   :width: 160px
   :align: center

**Simple, elegant wizarding tools for Python’s** ``dataclasses``.

📘 Docs → `dcw.ritviknag.com`_

.. image:: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml/badge.svg
   :target: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml
   :alt: CI Status

.. image:: https://img.shields.io/pypi/v/dataclass-wizard.svg
   :target: https://pypi.org/project/dataclass-wizard/
   :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/dataclass-wizard.svg
   :target: https://pypi.org/project/dataclass-wizard/
   :alt: Supported Python Versions

.. image:: https://static.pepy.tech/badge/dataclass-wizard
   :target: https://pepy.tech/project/dataclass-wizard
   :alt: Downloads per Month

**Dataclass Wizard** is a fast, well-tested serialization library for Python dataclasses.

-------------------

**Behold, the power of Dataclass Wizard**::

    >>> from __future__ import annotations
    >>> from dataclasses import field
    >>> from dataclass_wizard import DataclassWizard
    ...
    >>> class MyClass(DataclassWizard, load_case='AUTO', dump_case='CAMEL'):
    ...     my_str: str | None
    ...     is_active_tuple: tuple[bool, ...]
    ...     list_of_int: list[int] = field(default_factory=list)
    ...
    >>> MyClass.from_json(
    ...     '{"my_str": 20, "ListOfInt": ["1", "2", 3], "isActiveTuple": [true, false, 1]}'
    ... )
    MyClass(my_str='20', is_active_tuple=(True, False, True), list_of_int=[1, 2, 3])

.. note::
   The example above demonstrates automatic type coercion, key casing
   transforms, and support for nested dataclasses. ``DataclassWizard``
   also auto-applies ``@dataclass`` to subclasses.

.. tip::

   A new **v1 engine** is available as an opt-in, offering explicit
   environment precedence, nested dataclass support, and improved performance.

   ``EnvWizard`` v1 adds field-level configuration on top of these improvements.

   See the `Field Guide to V1 Opt-in`_ and the `hands-on quickstart`_ for details.

.. contents:: Contents
   :depth: 1
   :local:
   :backlinks: none

Why Dataclass Wizard?
---------------------

Dataclass Wizard helps you turn Python dataclasses into robust,
high-performance serialization schemas with minimal effort.

- 🚀 Fast — code-generated loaders and dumpers
- 🪶 Lightweight — pure Python, minimal dependencies
- 🧠 Typed — powered by Python type hints
- 🧙 Flexible — JSON, YAML, TOML, and environment variables
- 🧪 Reliable — battle-tested with extensive test coverage

Quick Examples
--------------

.. rubric:: JSON De/Serialization

.. code-block:: python3

    from dataclasses import dataclass
    from dataclass_wizard import JSONWizard

    @dataclass
    class Data(JSONWizard):
        value: int

    data = Data.from_dict({"value": "123"})
    assert data.value == 123
    print(data.to_json())

.. rubric:: Environment Variables

.. code-block:: python3

    import os
    from dataclass_wizard import EnvWizard

    os.environ['DEBUG'] = 'true'

    class Config(EnvWizard):
        debug: bool

    cfg = Config()
    assert cfg.debug is True

.. rubric:: EnvWizard v1 (Opt-in)

.. code-block:: python3

    import os
    from dataclass_wizard.v1 import EnvWizard, Env

    os.environ['DEBUG_MODE'] = 'true'


    class Config(EnvWizard):
        debug: bool = Env('DEBUG_MODE')


    cfg = Config()
    assert cfg.debug is True

.. tip::
   EnvWizard v1 introduces explicit environment precedence and nested
   dataclass support. See `Field Guide to V1 Opt-in`_ for full details.

Installation
------------

Install from `PyPI`_:

.. code-block:: console

    pip install dataclass-wizard

Or via `conda-forge`_:

.. code-block:: console

    conda install -c conda-forge dataclass-wizard

Dataclass Wizard supports **Python 3.9+**.

.. note::
   Python 3.6–3.8 users should install the last supported release,
   ``dataclass-wizard==0.26.1``.
   See `PyPI`_ for historical versions and the `Changelog`_ for details.

.. _PyPI: https://pypi.org/project/dataclass-wizard/
.. _conda-forge: https://conda-forge.org/
.. _Changelog: https://dcw.ritviknag.com/en/latest/history.html

Wizard Mixins ✨
----------------

In addition to ``JSONWizard``, Dataclass Wizard provides a set of focused
Mixin_ classes to simplify common serialization tasks:

- 🪄 `EnvWizard`_ — Load environment variables and ``.env`` files into typed schemas,
  including support for secret directories.
- 🎩 `JSONPyWizard`_ — A helper for ``JSONWizard`` that preserves keys as-is
  (no case transformations).
- 🔮 `JSONListWizard`_ — Extend ``JSONWizard`` to convert lists into container objects.
- 💼 `JSONFileWizard`_ — Load and save dataclass instances from local JSON files.

Optional format support:

- 🌳 `TOMLWizard`_ — Map dataclasses to and from TOML.
- 🧙‍♂️ `YAMLWizard`_ — Convert between YAML and dataclasses using ``

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `main@2026-06-01` | 2026-06-01 | High | Latest activity on main branch |
| `0.39.1` | 2026-04-21 | Low | Imported from PyPI (0.39.1) |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `main@2026-04-01` | 2026-04-01 | Medium | Latest activity on main branch |
| `v0.39.1` | 2026-01-06 | Low | Tag v0.39.1 |

## Citation

- HTML: https://www.freshcrate.ai/projects/dataclass-wizard
- Markdown: https://www.freshcrate.ai/projects/dataclass-wizard.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/dataclass-wizard/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._