{"id":2551,"library":"jsonargparse","title":"jsonargparse","description":"jsonargparse is a Python library that extends `argparse` to simplify the creation of Command-Line Interfaces (CLIs) and make Python applications easily configurable. It allows parsing configuration options from command line arguments, config files (JSON, YAML, Jsonnet, TOML), and environment variables, leveraging type hints for validation. It is a well-maintained project with frequent releases, adhering to high standards of development, including semantic versioning, deprecation periods, changelog, automated testing, and full test coverage.","status":"active","version":"4.48.0","language":"en","source_language":"en","source_url":"https://github.com/omni-us/jsonargparse","tags":["CLI","argparse","configuration","YAML","JSON","type-hints","dependency-injection","config-files","environment-variables"],"install":[{"cmd":"pip install jsonargparse","lang":"bash","label":"Base installation"},{"cmd":"pip install \"jsonargparse[all]\"","lang":"bash","label":"Install with all optional dependencies (e.g., signatures, jsonschema, jsonnet, urls, argcomplete)"}],"dependencies":[{"reason":"Default dependency for YAML config file support.","package":"PyYAML","optional":false},{"reason":"Required for JSON Schema validation features.","package":"jsonschema","optional":true},{"reason":"Required for Jsonnet config file support.","package":"jsonnet","optional":true},{"reason":"Required for URL parsing functionality.","package":"validators","optional":true},{"reason":"Required for URL parsing functionality (e.g., checking accessibility).","package":"requests","optional":true},{"reason":"Required for command-line tab completion.","package":"argcomplete","optional":true},{"reason":"Required for advanced command-line tab completion (alternative to argcomplete).","package":"shtab","optional":true}],"imports":[{"symbol":"ArgumentParser","correct":"from jsonargparse import ArgumentParser"},{"note":"While 'CLI' originates from 'jsonargparse.cli', the public API encourages importing directly from the top-level 'jsonargparse' module to ensure stability against internal refactoring.","wrong":"from jsonargparse.cli import CLI","symbol":"CLI","correct":"from jsonargparse import CLI"},{"note":"Similar to CLI, 'auto_cli' is exposed at the top level for public API stability.","wrong":"from jsonargparse.cli import auto_cli","symbol":"auto_cli","correct":"from jsonargparse import auto_cli"}],"quickstart":{"code":"from jsonargparse import CLI\n\ndef main(name: str, greeting: str = 'Hello') -> None:\n    \"\"\"\n    A simple command-line interface function.\n\n    Args:\n        name: The name of the person to greet.\n        greeting: The greeting message to use.\n    \"\"\"\n    print(f'{greeting}, {name}!')\n\nif __name__ == '__main__':\n    # Run this from the command line:\n    # python your_script.py --name World\n    # python your_script.py --name Alice --greeting Hi\n    CLI(main)","lang":"python","description":"The simplest way to create a CLI is by using the `CLI()` function with a type-hinted Python function. `jsonargparse` automatically generates arguments, validates types, and uses docstrings for help messages."},"warnings":[{"fix":"If you relied on the `argparse`-like default exit-on-error behavior, you can re-enable it by setting `error_handler=usage_and_exit_error_handler` during `ArgumentParser` instantiation. For `error_handler` and `formatter_class`, pass callable objects directly instead of strings.","message":"In `jsonargparse` v4.0.0, the default error handling behavior of `ArgumentParser` changed. It now raises a `ParserError` by default on parsing failure instead of printing usage and exiting the program. Additionally, `error_handler` and `formatter_class` arguments no longer accept string values.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update imports and class references from `SimpleNamespace` to `Namespace`. Ensure your code handles `Namespace` objects appropriately for parsed arguments.","message":"The internal `SimpleNamespace` class was replaced by `Namespace` in `jsonargparse` v4.0.0 to align more closely with `argparse`. Code directly interacting with `jsonargparse.namespace.SimpleNamespace` might break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"For boolean arguments, use `parser.add_argument('--flag', action=ActionYesNo)` or `type=bool` with a default value, which `jsonargparse` handles correctly with `--flag`, `--no-flag`, or environment variables like `FLAG=true/false`.","message":"Using `type=bool` directly in `add_argument` for boolean flags in standard `argparse` (and by extension, potentially `jsonargparse` if not careful) does not behave as expected for command-line parsing, as it treats any non-empty string as `True`. `jsonargparse` provides `ActionYesNo` for clear boolean handling.","severity":"gotcha","affected_versions":"All"},{"fix":"Design your CLIs to have all arguments explicitly defined or use subcommands. If you truly need to ignore unknown arguments, you might need to process `sys.argv` manually before passing to `jsonargparse` or implement custom parsing logic, but this is generally discouraged for robust applications.","message":"The `ArgumentParser.parse_known_args()` method is intentionally not implemented in `jsonargparse` to prevent typos in configuration files or arguments from going unnoticed. If `parse_known_args` were allowed, unknown arguments would be silently ignored, potentially hiding critical configuration errors.","severity":"gotcha","affected_versions":"All"},{"fix":"To enable environment variable parsing for `parse_args()`, initialize your parser with `ArgumentParser(default_env=True)`. Alternatively, use `parser.parse_env()` to parse only environment variables.","message":"By default, `ArgumentParser.parse_args()` does not check environment variables. You must explicitly enable this behavior.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}