{"id":5915,"library":"draccus","title":"draccus","description":"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.","status":"active","version":"0.11.5","language":"en","source_language":"en","source_url":"https://github.com/marin-community/draccus","tags":["configuration","dataclass","cli","yaml","argparse"],"install":[{"cmd":"pip install draccus","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Draccus is a fork of Pyrallis and builds upon its core functionality for dataclass-based argument parsing and configuration management.","package":"pyrallis"}],"imports":[{"note":"The `@draccus.wrap()` decorator is the primary entry point for integrating dataclass configurations with argument parsing.","symbol":"wrap","correct":"import draccus\n@draccus.wrap(...)\ndef main(cfg: Config): ..."},{"note":"Use `draccus.parse()` for manual parsing of a configuration dataclass, typically when not using the `@draccus.wrap()` decorator.","symbol":"parse","correct":"import draccus\ncfg = draccus.parse(config_class=Config)"}],"quickstart":{"code":"from dataclasses import dataclass\nimport draccus\n\n@dataclass\nclass TrainConfig:\n    \"\"\"Training Config for Machine Learning\"\"\"\n    workers: int = 8  # The number of workers for training\n    exp_name: str = 'default_exp' # The experiment name\n\n@draccus.wrap()\ndef main(cfg: TrainConfig):\n    print(f\"Training {cfg.exp_name} with {cfg.workers} workers...\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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`."},"warnings":[{"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.","message":"Draccus 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refactor your main application entry point to use the `@draccus.wrap()` decorator for a more streamlined and idiomatic approach to configuration management.","message":"Earlier 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.","severity":"deprecated","affected_versions":"<0.10.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}