Pre-release

This release is a pre-release and may not be stable for production use.

https://readthedocs.org/projects/jsonargparse/badge/?version=stable

https://github.com/mauvilsa/jsonargparse/actions/workflows/tests.yaml/badge.svg

https://codecov.io/gh/mauvilsa/jsonargparse/branch/main/graph/badge.svg

jsonargparse

Docs: https://jsonargparse.readthedocs.io/ | Source: https://github.com/mauvilsa/jsonargparse/

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. Most notably, it serves as the framework behind pytorch-lightning’s LightningCLI.

The documentation is a reference that describes each feature in isolation, which is not always the best way to learn. If you would rather see the why behind the features and complete use cases built end to end, have a look at the talks and articles page, which collects presentations, blog posts and example projects.

Teaser examples

CLI with minimal boilerplate:

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:

from jsonargparse import auto_parser

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

Powerful argparse-like low level parsers:

from jsonargparse import ArgumentParser

parser = ArgumentParser()
parser.add_argument("--config", action="config")  # support config files
parser.add_argument("--opt", type=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, Typer, Clize and Tyro.
Use type hints for argument validation, like Typer, Tap and Tyro.
Use of docstrings for automatic generation of help, like Tap, Tyro and SimpleParsing.
Parse from configuration files and environment variables, like OmegaConf, dynaconf, confuse and configargparse.
Dataclasses support, like SimpleParsing and 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), and backports (PEP 604).
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, yaml, toml, jsonnet 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.
Tab completion: powered by shtab or argcomplete.

Design principles

Non-intrusive/decoupled:

There is no requirement for unrelated modifications throughout a codebase, maintaining the separation of concerns principle. 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. 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, is a sound design pattern for developing loosely coupled and highly configurable software. Such type hints should be supported with minimal restrictions.

Installation

You can install using pip as:

pip install jsonargparse

jsonargparse has no required dependencies. Optional features are enabled by specifying one or more of the following extras (optional dependencies): signatures, docstrings, typeshed, yaml, jsonschema, jsonnet, urls, fsspec, toml, ruamel, omegaconf, shtab, and argcomplete. The yaml extra installs PyYAML, without which config files are parsed only as JSON. The signatures extra includes docstrings and typeshed, which can also be installed individually. 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:

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:

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

Metadata

Release files for jsonargparse 5.0.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jsonargparse 5.0.0rc1
File	Size	Uploaded	Provenance
jsonargparse-5.0.0rc1.tar.gz	177.5 kB	Oct 9, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for jsonargparse 5.0.0rc1
File	Interpreter	ABI	Platform	Reset
jsonargparse-5.0.0rc1-py3-none-any.whl 187.1 kB Oct 9, 2026 With provenance	Python 3	none	any	Details

Total release size: 364.6 kB

Release files / jsonargparse-5.0.0rc1.tar.gz

Download URL	jsonargparse-5.0.0rc1.tar.gz
Size	177.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`3962328953e5983ca4fcdd13f0b3095f4cb1325e65bf8053da50d55079a3496e`
BLAKE2b-256 checksum How to use checksums	`dfb07a3cf113cf2d8958ec49ccb25134ab156cc6b117e4e03c1e13ebbf349bc4`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mauvilsa/jsonargparse
Publishing commit: github.com/mauvilsa/jsonargparse/tree/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e

Workflow

Publishing configuration: github.com/mauvilsa/jsonargparse/blob/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e/.github/workflows/tests.yaml
Publishing logs: github.com/mauvilsa/jsonargparse/actions/runs/37895437024/attempts/1

Artifact

Subject: jsonargparse-5.0.0rc1.tar.gz
SHA-256 checksum: 3962328953e5983ca4fcdd13f0b3095f4cb1325e65bf8053da50d55079a3496e Verifying attestations

Release files / jsonargparse-5.0.0rc1-py3-none-any.whl

Download URL	jsonargparse-5.0.0rc1-py3-none-any.whl
Size	187.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`158d305e1e68952619634ad1be0eb6fadfdfb86282bca44b677684e5a7e1e693`
BLAKE2b-256 checksum How to use checksums	`5350f0ee81cb56b3060b04edb91e02571212bfb2aaaf91379b240b23a9b4caa7`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mauvilsa/jsonargparse
Publishing commit: github.com/mauvilsa/jsonargparse/tree/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e

Workflow

Publishing configuration: github.com/mauvilsa/jsonargparse/blob/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e/.github/workflows/tests.yaml
Publishing logs: github.com/mauvilsa/jsonargparse/actions/runs/37895437024/attempts/1

Artifact

Subject: jsonargparse-5.0.0rc1-py3-none-any.whl
SHA-256 checksum: 158d305e1e68952619634ad1be0eb6fadfdfb86282bca44b677684e5a7e1e693 Verifying attestations

Security for jsonargparse 5.0.0rc1

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for jsonargparse-5.0.0rc1.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mauvilsa/jsonargparse
Publishing commit: github.com/mauvilsa/jsonargparse/tree/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e

Workflow

Publishing configuration: github.com/mauvilsa/jsonargparse/blob/7557e756aa6751c2b3bd921c7a91feb5f74e5a5e/.github/workflows/tests.yaml
Publishing logs: github.com/mauvilsa/jsonargparse/actions/runs/37895437024/attempts/1

Artifact

Subject: jsonargparse-5.0.0rc1.tar.gz
SHA-256 checksum: 3962328953e5983ca4fcdd13f0b3095f4cb1325e65bf8053da50d55079a3496e Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.