jsonargparse

4.48.0 · active · verified Fri Apr 10

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.

Warnings

breaking 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.
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.
breaking 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.
Fix: Update imports and class references from `SimpleNamespace` to `Namespace`. Ensure your code handles `Namespace` objects appropriately for parsed arguments.
gotcha 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.
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`.
gotcha 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.
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.
gotcha By default, `ArgumentParser.parse_args()` does not check environment variables. You must explicitly enable this behavior.
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.

Install

pip install jsonargparse Base installation
pip install "jsonargparse[all]" Install with all optional dependencies (e.g., signatures, jsonschema, jsonnet, urls, argcomplete)

Imports

ArgumentParser
```
from jsonargparse import ArgumentParser
```
CLI
```
from jsonargparse import CLI
```
While 'CLI' originates from 'jsonargparse.cli', the public API encourages importing directly from the top-level 'jsonargparse' module to ensure stability against internal refactoring.
auto_cli
```
from jsonargparse import auto_cli
```
Similar to CLI, 'auto_cli' is exposed at the top level for public API stability.

Quickstart

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.

from jsonargparse import CLI

def main(name: str, greeting: str = 'Hello') -> None:
    """
    A simple command-line interface function.

    Args:
        name: The name of the person to greet.
        greeting: The greeting message to use.
    """
    print(f'{greeting}, {name}!')

if __name__ == '__main__':
    # Run this from the command line:
    # python your_script.py --name World
    # python your_script.py --name Alice --greeting Hi
    CLI(main)

view raw JSON →