jsonargparse

jsonargparse 是基于Python标准库argparse扩展的配置+命令行解析库，广泛用于AI/科研项目（PyTorch‑Lightning底层就在用），同时解析命令行、yaml/json配置文件、环境变量，支持嵌套结构化配置，兼容dataclass、类型提示，大幅减少命令行样板代码。

pip install jsonargparse
 
# 可选扩展
pip install jsonargparse[signatures,jsonnet]

核心定位

原生argparse痛点：

只解析命令行，不支持yaml/json配置文件
嵌套配置写起来极其啰嗦
需要手动写大量add_argument()
环境变量要自己处理

jsonargparse解决：一套参数同时来自命令行 + 配置文件 + 环境变量，支持层级嵌套，类型提示自动生成CLI。

✨核心特性

兼容argparse写法：原有ArgumentParser代码几乎可以直接迁移，学习成本低
多来源配置合并，优先级（高→低）
```
命令行参数 > 环境变量 > 默认配置文件 > 代码内default值
```
命令行可以传--config xxx.yaml加载配置文件，再用命令行覆盖部分字段。
嵌套层级Namespace，支持yaml分层配置，命令行用--model.lr=0.01这种点语法修改嵌套字段
类型提示自动生成CLI（auto_cli）：函数/类的type hint、docstring自动变成命令行参数，不用写add_argument
支持 yaml / json / jsonnet / toml；配置内部相对路径自动解析
dataclass原生支持，可把dataclass直接作为参数schema
对象注入：配置里指定类路径，自动实例化对象（深度学习实验非常好用）
shell补全、json‑schema校验等附加能力

简单示例

示例1：兼容argparse传统写法

from jsonargparse import ArgumentParser
 
parser = ArgumentParser()
parser.add_argument("--lr", type=float, default=1e-3)
parser.add_argument("--model.name", type=str, default="resnet")
# 加载配置文件
parser.add_argument("--config", action="config_file")
 
cfg = parser.parse_args()
print(cfg.lr, cfg.model.name)

运行：

python main.py --config config.yaml --model.name=vit

示例2：auto_cli，最少代码（推荐）

从函数签名+docstring自动构建cli，不用手动add_argument。

from jsonargparse import auto_cli
 
def train(lr:float=0.001, epochs:int=10):
    """训练模型
    Args:
        lr:学习率
        epochs:训练轮数
    """
    print(lr, epochs)
 
if __name__ == "__main__":
    auto_cli(train)

python main.py --lr 0.01 --epochs 20
python main.py --help

示例3：dataclass结构化配置

from dataclasses import dataclass
from jsonargparse import ArgumentParser
 
@dataclass
class ModelConfig:
    name: str
    lr: float = 1e-3
 
@dataclass
class TrainConfig:
    model: ModelConfig
    epochs: int = 10
 
parser = ArgumentParser()
parser.add_dataclass_arguments(TrainConfig)
cfg = parser.parse_args()
print(cfg.model.lr)

命令行修改嵌套字段：

python main.py --model.lr 0.005

config.yaml示例（嵌套）

model:
  name: resnet50
  lr: 0.0005
epochs: 20

python main.py --config config.yaml --model.lr 0.01

和同类库对比

库	特点
argparse	标准库；仅命令行；无配置文件；样板代码多
jsonargparse	argparse超集；命令行+yaml+env；dataclass；对象实例化；科研AI项目常用；可渐进迁移原有argparse代码
OmegaConf	侧重配置对象；命令行能力弱；常和Hydra搭配
ConfigArgParse	argparse扩展，支持配置文件，但对嵌套、类型提示支持弱
Typer	侧重命令行应用；配置文件支持不是强项

关键区别：jsonargparse保留完整argparse接口，旧项目迁移代价很小，同时擅长实验场景，配置文件与命令行混合覆写，支持从配置实例化Python类，所以被pytorch‑lightning大量使用。

常见坑

优先级不要搞混：命令行 > 环境变量 > 配置文件 > 默认值；命令行会覆盖yaml里的值。
嵌套参数命令行必须用点号--model.lr=0.1，不能下划线。
auto_cli需要安装[signatures]可选依赖，否则部分类型解析会报错。
可以区分“参数没传”和“显式设置None”：开启unset_sentinel=True使用Unset标记对象。
配置文件内的相对路径，会以配置文件所在目录为基准解析，不是进程cwd。

适用场景

✅ 深度学习/科研实验脚本：大量超参，需要yaml配置，又要命令行快速调参 ✅ 已有argparse老项目，想增加yaml配置，不想完全重写 ✅ 需要多层嵌套结构化配置 ❌ 如果只是简单单文件cli工具，直接用typer更轻

如果你需要，我可以写一个最小可运行demo，包含dataclass+yaml配置+命令行覆写完整例子。

知识花园

探索