jsonargparse is a library for creating command-line interfaces (CLIs) and making Python apps easily configurable. It is a well-maintained project with frequent releases, adhering to high standards of development: semantic versioning, deprecation periods, changelog, automated testing, and full test coverage.

Although jsonargparse might not be widely recognized yet, it already boasts a substantial user base <https://github.com/omni-us/jsonargparse/network/dependents>. Most notably, it serves as the framework behind pytorch-lightning's LightningCLI <https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html>.

Teaser examples

CLI with minimal boilerplate:

.. code-block:: python

from jsonargparse import auto_cli

def main_function(...):  # your main parameters with type hints here
    ...  # your main code here

if __name__ == "__main__":
    auto_cli(main_function)  # parses arguments and runs main_function

Minimal boilerplate but manually parsing:

.. code-block:: python

from jsonargparse import auto_parser

parser = auto_parser(main_function)
cfg = parser.parse_args()
...

Powerful argparse-like low level parsers:

.. code-block:: python

from jsonargparse import ArgumentParser

parser = ArgumentParser()
parser.add_argument("--config", action="config")  # support config files
parser.add_argument("--opt", type=Union[int, Literal["off"]])  # complex arguments via type hints
parser.add_function_arguments(main_function, "function")  # add function parameters
parser.add_class_arguments(SomeClass, "class")  # add class parameters
...
cfg = parser.parse_args()
init = parser.instantiate(cfg)
...

Features

jsonargparse is user-friendly and encourages the development of clean, high-quality code. It encompasses numerous powerful features, some unique to jsonargparse, while also combining advantages found in similar packages:

Automatic creation of CLIs, like Fire <https://pypi.org/project/fire/>, Typer <https://pypi.org/project/typer/>, Clize <https://pypi.org/project/clize/>__ and Tyro <https://pypi.org/project/tyro/>__.
Use type hints for argument validation, like Typer <https://pypi.org/project/typer/>, Tap <https://pypi.org/project/typed-argument-parser/> and Tyro <https://pypi.org/project/tyro/>__.
Use of docstrings for automatic generation of help, like Tap <https://pypi.org/project/typed-argument-parser/>, Tyro <https://pypi.org/project/tyro/> and SimpleParsing <https://pypi.org/project/simple-parsing/>__.
Parse from configuration files and environment variables, like OmegaConf <https://pypi.org/project/omegaconf/>, dynaconf <https://pypi.org/project/dynaconf/>, confuse <https://pypi.org/project/confuse/>__ and configargparse <https://pypi.org/project/ConfigArgParse/>__.
Dataclasses support, like SimpleParsing <https://pypi.org/project/simple-parsing/>__ and Tyro <https://pypi.org/project/tyro/>__.

Other notable features include:

Extensive type hint support: nested types (union, optional), containers (list, dict, etc.), protocols, user-defined generics, restricted types (regex, numbers), paths, URLs, types from stubs (*.pyi), future annotations (PEP 563 <https://peps.python.org/pep-0563/>), and backports (PEP 604 <https://peps.python.org/pep-0604>).
Keyword arguments introspection: resolving of parameters used via **kwargs.
Dependency injection: support types that expect a class instance and callables that return a class instance.
Structured configs: parse config files with more understandable non-flat hierarchies.
Config file formats: json <https://www.json.org/>, yaml <https://yaml.org/>, toml <https://toml.io/>, jsonnet <https://jsonnet.org/> and extensible to more formats.
Relative paths: within config files and parsing of config paths referenced inside other configs.
Argument linking: directing parsed values to multiple parameters, preventing unnecessary interpolation in configs.
Variable interpolation: powered by OmegaConf <https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation>__.
Tab completion: powered by shtab <https://pypi.org/project/shtab/>__ or argcomplete <https://pypi.org/project/argcomplete/>__.

Design principles

Non-intrusive/decoupled:

There is no requirement for unrelated modifications throughout a codebase, maintaining the separation of concerns principle <https://en.wikipedia.org/wiki/Separation_of_concerns>__. In simpler terms, changes should make sense even without the CLI. No need to inherit from a special class, add decorators, or use CLI-specific type hints.
Minimal boilerplate:

A recommended practice is to write code with function/class parameters having meaningful names, accurate type hints, and descriptive docstrings. Reuse these wherever they appear to automatically generate the CLI, following the don't repeat yourself principle <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>__. A notable advantage is that when parameters are added or types changed, the CLI will remain synchronized, avoiding the need to update the CLI's implementation.
Dependency injection:

Using as type hint a class or a callable that instantiates a class, a practice known as dependency injection <https://en.wikipedia.org/wiki/Dependency_injection>__, is a sound design pattern for developing loosely coupled and highly configurable software. Such type hints should be supported with minimal restrictions.

.. _installation:

Installation

You can install using pip <https://pypi.org/project/jsonargparse/>__ as:

.. code-block:: bash

pip install jsonargparse

By default, the only dependency installed with jsonargparse is PyYAML <https://pypi.org/project/PyYAML/>__. However, several optional features can be enabled by specifying one or more of the following extras (optional dependencies): signatures, jsonschema, jsonnet, urls, fsspec, toml, ruamel, omegaconf, shtab, and argcomplete. Additionally, the all extras can be used to enable all optional features (excluding tab completion ones). To install jsonargparse with extras, use the following syntax:

.. code-block:: bash

pip install "jsonargparse[signatures,urls]"  # Enable signatures and URLs features
pip install "jsonargparse[all]"              # Enable all optional features

To install the latest development version, use the following command:

.. code-block:: bash

pip install "jsonargparse[signatures] @ https://github.com/omni-us/jsonargparse/zipball/main"

分类

Development Status :: 5 - Production/Stable Intended Audience :: Developers Operating System :: MacOS Operating System :: Microsoft :: Windows Operating System :: POSIX :: Linux Programming Language :: Python Programming Language :: Python :: 3 Programming Language :: Python :: 3 :: Only Programming Language :: Python :: 3.10 Programming Language :: Python :: 3.11 Programming Language :: Python :: 3.12 Programming Language :: Python :: 3.13 Programming Language :: Python :: 3.14 Programming Language :: Python :: 3.9

版本列表

4.49.0 2026-05-15

4.48.0 2026-04-10

4.47.0 2026-03-13

4.46.0 2026-02-02

4.45.0 2025-12-26

4.44.0 2025-11-25

4.43.0 2025-11-11

4.42.0 2025-10-14

4.41.0 2025-09-04

4.40.2 2025-08-06

4.40.1 2025-07-24

4.40.0 2025-05-16

4.39.0 2025-04-29

4.38.0 2025-03-26

4.37.0 2025-02-14

4.36.0 2025-01-17

4.35.0 2024-12-16

4.34.1 2024-12-02

4.34.0 2024-11-08

4.33.2 2024-10-07

4.33.1 2024-09-26

4.32.1 2024-08-23

4.32.0 2024-07-19

4.31.0 2024-06-27

4.30.0 2024-06-18

4.29.0 2024-05-24

4.28.0 2024-04-17

4.27.7 2024-03-21

4.27.6 2024-03-15

4.27.5 2024-02-12

4.27.4 2024-02-01

4.27.3 2024-01-26

4.27.2 2024-01-18

4.27.1 2023-11-23

4.27.0 2023-11-02

4.26.2 2023-10-26

4.26.1 2023-10-23

4.26.0 2023-10-19

4.25.0 2023-09-25

4.24.1 2023-09-06

4.24.0 2023-08-23

4.23.1 2023-08-04

4.23.0 2023-07-27

4.22.1 2023-07-07

4.22.0 2023-06-23

4.21.2 2023-06-08

4.21.1 2023-05-09

4.21.0 2023-04-21

4.20.1 2023-03-30

4.20.0 2023-02-20

4.19.0 2022-12-27

4.18.0 2022-11-29

4.17.0 2022-11-11

4.16.0 2022-10-28

4.15.2 2022-10-20

4.15.1 2022-10-07

4.15.0 2022-09-27

4.14.1 2022-09-26

4.14.0 2022-09-14

4.13.3 2022-09-06

4.13.2 2022-08-31

4.13.1 2022-08-05

4.13.0 2022-08-03

4.12.0 2022-07-22

4.11.0 2022-07-12

4.10.2 2022-07-01

4.10.1 2022-06-29

4.10.0 2022-06-21

4.10.0.dev2 2022-06-16

4.10.0.dev1 2022-06-14

4.9.0 2022-06-01

4.8.0 2022-05-26

4.8.0.dev2 2022-05-25

4.8.0.dev1 2022-05-23

4.7.3 2022-05-10

4.7.2 2022-04-29

4.7.1 2022-04-26

4.7.0 2022-04-20

4.6.0 2022-04-11

4.6.0.dev3 2022-04-08

4.6.0.dev1 2022-04-05

4.5.0 2022-03-29

4.4.0 2022-03-18

4.3.1 2022-03-01

4.3.0 2022-02-22

4.2.0 2022-02-09

4.1.4 2022-01-26

4.1.3 2022-01-24

4.1.2 2022-01-20

4.1.1 2022-01-13

4.1.0 2021-12-06

4.0.4 2021-11-29

4.0.3 2021-11-23

4.0.2 2021-11-22

4.0.1 2021-11-22

4.0.0 2021-11-16

4.0.0.dev1 2021-11-04

4.0.0rc1 2021-11-09

3.19.4 2021-10-04

3.19.3 2021-09-16

3.19.2 2021-09-09

3.19.1 2021-09-03

3.19.0 2021-08-27

3.18.0 2021-08-18

3.17.0 2021-07-19

3.16.1 2021-07-13

3.16.0 2021-07-05

3.15.0 2021-06-22

3.14.0 2021-06-08

3.13.1 2021-06-03

3.13.0 2021-06-02

3.12.1 2021-05-19

3.12.0 2021-05-13

3.11.2 2021-05-03

3.11.1 2021-04-30

3.11.0 2021-04-27

3.10.1 2021-04-24

3.10.0 2021-04-19

3.9.0 2021-04-09

3.8.1 2021-03-22

3.8.0 2021-03-22

3.7.0 2021-03-17

3.6.0 2021-03-08

3.5.1 2021-02-26

3.5.0 2021-02-12

3.4.1 2021-02-03

3.4.0 2021-02-01

3.3.2 2021-01-22

3.3.1 2021-01-08

3.3.0 2021-01-08

3.2.1 2020-12-30

3.1.0 2020-12-09

3.0.1 2020-12-02

3.0.0 2020-12-01

3.0.0.dev5 2020-11-11

3.0.0.dev4 2020-11-02

3.0.0.dev3 2020-10-28

3.0.0.dev2 2020-10-27

3.0.0.dev1 2020-10-19

3.0.0rc4 2020-11-30

3.0.0rc3 2020-11-27

3.0.0rc2 2020-11-23

3.0.0rc1 2020-11-18

2.32.2 2020-07-23

2.32.1 2020-07-22

2.32.0 2020-07-21

2.31.2 2020-07-08

2.31.1 2020-06-19

2.31.0 2020-06-16

2.30.2 2020-05-30

2.30.0 2020-05-11

2.29.0 2020-05-07

2.28.0 2020-05-04

2.27.0 2020-04-26

2.26.1 2020-04-23

2.26.0 2020-04-23

2.25.4 2020-04-21

2.25.3 2020-04-03

2.25.2 2020-03-10

2.25.1 2020-03-04

2.25.0 2020-03-02

2.24.1 2020-02-28

2.24.0 2020-02-26

2.23.5 2020-02-19

2.23.4 2020-02-12

2.23.3 2020-02-10

2.23.2 2020-02-08

2.23.1 2020-01-30

2.23.0 2020-01-29

2.22.2 2020-01-26

2.22.1 2020-01-24

2.22.0 2020-01-21

2.21.0 2020-01-16

2.20.0 2020-01-09

2.19.0 2019-12-22

2.18.0 2019-12-20

2.17.0 2019-12-18

2.16.0 2019-12-16

2.15.0 2019-12-12

2.14.3 2019-12-11

2.14.2 2019-12-10

2.14.1 2019-12-10

2.14.0 2019-12-09

2.13.1 2019-12-06

2.13.0 2019-12-06

2.12.0 2019-11-30

2.11.0 2019-11-22

2.10.1 2019-11-13

2.9.0 2019-10-10

2.8.0 2019-10-10

2.7.0 2019-10-07

2.6.1 2019-09-17

2.6.0 2019-09-14

2.5.0 2019-09-13

2.4.1 2019-09-06

2.4.0 2019-09-06

2.3.0 2019-09-06

2.2.1 2019-09-02

2.1.1 2019-08-31

2.1.0 2019-08-27

2.0.0 2019-08-26