---
id: jsonargparse
version: "4.50.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# jsonargparse — Minimal effort CLIs derived from type hints and parse from command line, config files and environment variables.

License: permissive · Maintenance: active · Downloads: 3.4M/mo

## What it is and what it does

jsonargparse is a library for building command-line interfaces and making Python applications configurable without boilerplate. It reads your function or class signatures—their parameter names, type hints, and docstrings—and automatically generates a CLI that accepts arguments from the command line, YAML/JSON/TOML config files, or environment variables. It handles complex types (unions, optionals, nested dataclasses), dependency injection, and variable interpolation, all while keeping your core code free of CLI-specific decorators or inheritance.

The library is built on argparse but extends it significantly: it parses structured configs into nested hierarchies, supports multiple file formats, and can instantiate objects from parsed configurations. It's used as the foundation for pytorch-lightning's LightningCLI and is actively maintained with semantic versioning and full test coverage.

Use it for:

- Build a CLI tool that accepts both command-line flags and a YAML config file without writing separate parsing logic.
- Make a machine learning training script configurable via config files while keeping the training function clean and testable.
- Create a multi-step application where each step's parameters are defined as function arguments and automatically exposed to the CLI.
- Parse environment variables and config files into a structured dataclass without manual validation or type conversion.
- Support dependency injection in your CLI so users can swap implementations by changing config values.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

jsonargparse creates command-line interfaces and configuration systems from Python type hints and docstrings, parsing arguments from the command line, config files (JSON, YAML, TOML, Jsonnet), and environment variables.

Yes. jsonargparse is a solid choice for any Python project needing a CLI or configuration system. It has low install friction (one required dependency), active maintenance, no known vulnerabilities, and a permissive license. The design is non-intrusive—your code remains clean and testable. Use it if you want to avoid hand-writing argparse boilerplate or if you need config file support beyond what argparse provides.

## Install

pip install jsonargparse
uv add jsonargparse
poetry add jsonargparse

## Installing jsonargparse

Before you install: Low friction: pure Python wheel with only PyYAML as a required runtime dependency. Active maintenance with a release 23 days ago and consistent commit history. Supports Python 3.10 through 3.14.

License in practice: MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart:

pip install jsonargparse

from jsonargparse import auto_cli

def main(name: str, count: int = 1):
    for _ in range(count):
        print(f"Hello {name}")

if __name__ == "__main__":
    auto_cli(main)

Verify before relying:

- Whether the 'substantial user base' claim is quantified beyond pytorch-lightning's LightningCLI adoption.
- Performance characteristics when parsing very large config files or deeply nested structures.
- Compatibility guarantees with optional dependencies (OmegaConf, shtab, argcomplete) across versions.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

CLI from type hints, command line argument parser, config file parsing, automatic CLI generation, structured configuration, argparse with config files, type-hint based CLI, cli-framework, config-management, type-hints

[View on SkillFed](https://skillfed.io/packages/jsonargparse) · [View on PyPI](https://pypi.org/project/jsonargparse/)