{"id":6789,"library":"pydantic-argparse","title":"Typed Argument Parsing with Pydantic","description":"pydantic-argparse is a Python package that provides declarative typed argument parsing by leveraging Pydantic models. It builds on the standard `argparse` module, offering a simple, opinionated, and type-hinted API for command-line interfaces. The library supports nesting Pydantic models for sub-command functionality and utilizes Pydantic's robust validation system. The current version is 0.10.0, released in February 2025, indicating an active development and release cadence.","status":"active","version":"0.10.0","language":"python","source_language":"en","source_url":"https://github.com/SupImDos/pydantic-argparse","tags":["pydantic","argparse","cli","command-line","typed","validation","settings"],"install":[{"cmd":"pip install pydantic-argparse","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for defining argument models and validation.","package":"pydantic","optional":false}],"imports":[{"symbol":"ArgumentParser","correct":"from pydantic_argparse import ArgumentParser"},{"note":"While pydantic-argparse added initial Pydantic v2 compatibility in v0.9.0, its official quickstart examples still explicitly import `pydantic.v1` for model definition. This suggests that using Pydantic v1 might be more stable or intended with current examples, or that full v2 migration requires careful adaptation of Pydantic models.","wrong":"from pydantic.v1 import BaseModel","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"import pydantic.v1 as pydantic\nfrom pydantic import Field\nfrom pydantic_argparse import ArgumentParser\n\nclass Arguments(pydantic.BaseModel):\n    \"\"\"Simple Command-Line Arguments.\"\"\"\n    # Required Args\n    string: str = Field(description=\"a required string\", aliases=[\"-s\"])\n    integer: int = Field(description=\"a required integer\", aliases=[\"-i\"])\n    flag: bool = Field(description=\"a required flag\", aliases=[\"-f\"])\n\n    # Optional Args\n    second_flag: bool = Field(False, description=\"an optional flag\")\n    third_flag: bool = Field(True, description=\"an optional flag\")\n\ndef main() -> None:\n    \"\"\"Simple Main Function.\"\"\"\n    parser = ArgumentParser(\n        model=Arguments,\n        prog=\"Example Program\",\n        description=\"Example Description\",\n        version=\"0.0.1\",\n        epilog=\"Example Epilog\",\n    )\n    args = parser.parse_typed_args()\n    print(args)\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"Define your command-line arguments using a Pydantic `BaseModel`. Then, create an instance of `pydantic_argparse.ArgumentParser` with your model and call `parse_typed_args()` to get a validated Pydantic model instance. This example uses `pydantic.v1` as shown in the official documentation."},"warnings":[{"fix":"For new projects, decide whether to explicitly use `pydantic.v1` for full compatibility with existing `pydantic-argparse` examples, or to adapt your Pydantic models to v2 and test thoroughly. If using Pydantic v2, consult the Pydantic migration guide for changes to `BaseModel` configuration and validators. The library's main `ArgumentParser` import remains consistent.","message":"Pydantic v1 vs v2 Compatibility: While pydantic-argparse v0.9.0 introduced initial compatibility with Pydantic v2, the official quickstart examples (even for v0.10.0) continue to explicitly use `import pydantic.v1 as pydantic`. Pydantic v2 includes significant breaking changes to its API (e.g., `Config` class vs `model_config` dict, `@validator` vs `@field_validator`, behavior of `Optional` fields). Users migrating from Pydantic v1 to v2 should carefully review the Pydantic migration guide and adapt their argument models, as direct compatibility with `pydantic-argparse` may require specific Pydantic v1 imports or adjustments.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Update code that inspects `model.__fields_set__` or uses `model.json(exclude_unset=True)` to account for the new behavior where only explicitly provided arguments are marked as 'set'.","message":"Changes to Default Value Handling (v0.6.0): Prior to v0.6.0, `pydantic-argparse` explicitly set default values for arguments not provided by the user via `argparse`. From v0.6.0 onwards, it transitioned to using `argparse.SUPPRESS` and relies on the `pydantic` model's default values for missing arguments. This change impacts how `model.__fields_set__` and `model.json(exclude_unset=True)` behave, as arguments not provided by the user will no longer appear in `__fields_set__`.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Always define arguments using `pydantic.Field` with implicit or explicit aliases (flags) for all command-line inputs. Do not attempt to define positional arguments through the Pydantic model.","message":"No Positional Arguments: `pydantic-argparse` has an opinionated design that explicitly does not support positional arguments, only optional and required arguments which are defined with flags. Users accustomed to `argparse`'s positional argument behavior may find this limiting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult Pydantic's `BaseSettings` documentation for environment variable loading order and precedence when designing your CLI with environment variable support. Clearly document the expected behavior for your users.","message":"Environment Variable Precedence: Version 0.8.0 introduced handling for environment variables, leveraging `pydantic.BaseSettings` for configuration. While a powerful feature, users should be aware of the precedence rules if arguments can be supplied via both command-line flags and environment variables, as the order of overriding might not always be intuitive without consulting Pydantic's settings documentation.","severity":"gotcha","affected_versions":">=0.8.0"}],"env_vars":null,"search_vec":"'0.10.0':66 '2025':70 'activ':73 'api':38 'argpars':8,28,79 'argument':2,17 'build':24 'cadenc':77 'cli':80 'command':41,53,82 'command-lin':40,81 'current':63 'declar':15 'develop':74 'februari':69 'function':54 'hint':37 'indic':71 'interfac':43 'leverag':20 'librari':45 'line':42,83 'model':22,49 'modul':29 'nest':47 'offer':30 'opinion':33 'packag':12 'pars':3,18 'provid':14 'pydant':5,7,21,48,57,78 'pydantic-argpars':6 'python':11 'releas':67,76 'robust':59 'set':86 'simpl':32 'standard':27 'sub':52 'sub-command':51 'support':46 'system':61 'type':1,16,36,84 'type-hint':35 'util':56 'valid':60,85 'version':64","created_at":"2026-04-15T18:43:03.129331+00:00","updated_at":"2026-04-16T18:23:38.132815+00:00","problems":[{"fix":"Ensure the library is installed using pip: `pip install pydantic-argparse`.","cause":"The `pydantic-argparse` library has not been installed, or the Python environment where it's installed is not the one being used to run the code.","error":"ModuleNotFoundError: No module named 'pydantic_argparse'"},{"fix":"Supply the missing argument on the command line. For example, if 'name' is required, run `python your_script.py --name 'value'`.","cause":"A required command-line argument, as defined in the Pydantic model used by `pydantic-argparse`, was not provided when the script was executed.","error":"error: the following arguments are required: ARG_NAME"},{"fix":"Reorder the fields in your Pydantic model so that all fields without default values (required arguments) are declared before any fields with default values (optional arguments).","cause":"This Pydantic-related error occurs when defining a Pydantic `BaseModel` (used by `pydantic-argparse`) where a field with a default value is declared before a field that has no default value (i.e., a required field).","error":"TypeError: Field 'field_name' has a non-default argument following a default argument"},{"fix":"Provide input values that match the expected type hint for each field in your Pydantic model. For example, for an `int` field, provide a numeric string like '123' instead of non-numeric text.","cause":"The value provided for a command-line argument could not be coerced into the expected Pydantic type (e.g., a string 'abc' was provided for an `int` field), failing Pydantic's validation.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for Arguments\nfield_name\n  Input should be a valid integer [type=int_parsing, ...]"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://pydantic-argparse.supimdos.com","github":"https://github.com/SupImDos/pydantic-argparse","docs":"https://pydantic-argparse.supimdos.com","changelog":"https://github.com/SupImDos/pydantic-argparse/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/pydantic-argparse/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}