Registry / serialization / draccus

draccus

JSON →
library0.11.6pypypi✓ verified 89d ago

Draccus is a Python library that provides a slightly opinionated framework for simple dataclass-based configurations, built as a fork of Pyrallis. It extends Pyrallis with advanced features such as support for subtyping configurations, the ability to include config files within other config files, and enhanced handling for containers of configurations. The current version is 0.11.5.

pip install draccus
INSTALL
IMPORT
SIG · DRACCUS
D
draccus
serializationpythonv0.11.6
Install
2.0s avg
Import
106ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.11.6 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.112s · 21.4MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 2.0s · import 0.101s · 23MB
20MB installed
● package 20MB
Code
Verified usage

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

wrap
✓ from draccus import wrap
✗ import draccus
field
✓ from draccus import field
ConfigType
✓ from draccus import ConfigType

This example demonstrates how to define a simple dataclass for configuration and use the `@draccus.wrap()` decorator to parse command-line arguments or YAML files into an instance of that dataclass. Run it from the command line, for example: `python your_script.py --exp_name=my_first_exp --workers=4`.

from dataclasses import dataclass import draccus @dataclass class TrainConfig: """Training Config for Machine Learning""" workers: int = 8 # The number of workers for training exp_name: str = 'default_exp' # The experiment name @draccus.wrap() def main(cfg: TrainConfig): print(f"Training {cfg.exp_name} with {cfg.workers} workers...") if __name__ == "__main__": main()
Debug
Known issues
gotchaDraccus is a fork of Pyrallis. While it maintains much of Pyrallis's API, it introduces unique features like subtyping and nested config file inclusion. Code expecting direct Pyrallis behavior for these advanced scenarios might need adaptation.
fix
Consult Draccus documentation for differences, especially when using ChoiceRegistry, nested config files, or containers of configs. Prefer `draccus`'s own decorators and functions over direct `pyrallis` imports if you intend to use Draccus-specific features.
affects: All versions
gotchaWhen using the `@draccus.wrap()` decorator, the decorated function's parameters are automatically populated by the parsed configuration. Avoid manually calling `draccus.parse()` within a function already wrapped by `@draccus.wrap()` unless a separate parsing context is explicitly intended.
fix
Ensure that `draccus.wrap()` is applied directly to your main entry point function, and let it handle the configuration injection. If explicit parsing is needed for a sub-component, consider making it a separate, unwrapped function or using `draccus.parse()` directly where appropriate.
affects: All versions
deprecatedEarlier versions might have used `draccus.parse()` as the primary entry point. While still available, `@draccus.wrap()` is generally recommended for top-level application configuration due to its seamless integration.
fix
Refactor your main application entry point to use the `@draccus.wrap()` decorator for a more streamlined and idiomatic approach to configuration management.
affects: <0.10.0
Upgrade
Version history
0.11.6latest on PyPI · released Jun 12, 2026
Audit
Dependencies
pyrallisrequiredDraccus is a fork of Pyrallis and builds upon its core functionality for dataclass-based argument parsing and configuration management.
Agent activity
29 hits · last 30 days
node
26
Resources
draccus — pip install draccus · libregistry