Python argparse 入门：把脚本变成“命令行工具”，并用 .sh 批量跑实验

在写 Python 脚本时，经常会有以下需求：

• 想在运行脚本时传入不同参数（比如 --lr 0.001 --epochs 20）
• 希望用户输入错误时能有清晰提示
• 希望自动生成 --help 帮助文档
• 想批量对比多组参数的运行结果（用 .sh 一键跑一堆实验）

argparse 就是 Python 标准库中专门解决这些问题的命令行参数解析工具。➡️

---

1. argparse 是干什么的？

argparse 的作用可以概括为一句话：

把命令行里的一串字符串参数，解析成 Python 里可直接使用的变量，并自动提供帮助信息和输入校验。

如果希望用户在命令行里像下面这样带参数运行：

python train.py --epochs 20 --lr 0.001 --device cuda

argparse 就负责把 --epochs 20、--lr 0.001 等解析成 Python 变量：

• args.epochs == 20（整数）
• args.lr == 0.001（浮点数）
• args.device == "cuda"（字符串，并可限制范围）

并且支持查看帮助：

python train.py --help
# 或
python train.py -h

自动生成用法说明和参数解释。

---

2. 最小例子：读取一个位置参数（必须提供）

下面的脚本要求用户必须提供一个名字：

# hello.py
import argparse

def main():
    parser = argparse.ArgumentParser(description="Say hello to someone.")
    parser.add_argument("name", help="The person's name")
    args = parser.parse_args()
    print(f"Hello, {args.name}!")

if __name__ == "__main__":
    main()

上面四个环节就是使用 argparse 的基本流程。

2.1 ArgumentParser(...)：创建解析器对象 parser

parser = argparse.ArgumentParser(description="xxx")

• ArgumentParser 是 argparse 提供的核心类
• description 会显示在 --help 的顶部

单双引号 "" 或 '' 都可以，Python 中几乎等价。

差别只在转义方便性，比如字符串里本身有单引号时：

• "I'm ok" 方便
• 'I\'m ok' 也行但要转义

2.2 add_argument(...)：声明一个参数的“规则”

在这里定义参数名、类型、默认值、是否必填、帮助说明等。

位置参数（不带 --）：

parser.add_argument("name", help="The person's name")

可选参数（带 --）：

parser.add_argument("--name", default="World", help="The person's name")

2.3 parse_args()：真正去“读取并解析命令行”

这一行会从命令行读取输入并解析：

args = parser.parse_args()

解析结果 args 是一个对象，用 args.xxx 访问对应参数。

没有这行，前面只是“定义规则”，还没有真正读取命令行。

2.4 运行方式

python hello.py Alice

输出：

Hello, Alice!

如果只运行：

python hello.py

会报错：

usage: hello.py [-h] name        # 语法格式摘要
hello.py: error: the following arguments are required: name

• [-h]：表示 可选参数 -h（或 --help）
  • 方括号 [...] 在 usage 里表示可选
• name：表示必填的位置参数
  • 没有方括号包起来，说明它必须提供
  • 位置参数的特点是：不写 --name 这种前缀，直接按顺序给值
• 运行 hello.py 时，可以选择加 -h/--help，但必须提供一个 name。

如果运行：

python hello.py --help

会输出：

usage: hello_01.py [-h] name

Say hello to someone.               # description

positional arguments:
  name        The person's name

options:
  -h, --help  show this help message and exit

• 显示完就退出，不会执行 print(f"Hello...")
  • 运行 python hello.py --help Alice 之后命令行输出与上面一致，不会打印。
• --help 是为了让用户快速知道怎么用，
  • 能看到自动生成的参数说明，避免“必须看源码才能知道怎么传参”。
• hello.py 中的 help= 里面的内容也可以写中文
  • 只要终端支持 UTF-8（Linux/macOS 一般没问题；Windows 建议用 Windows Terminal / PowerShell）。

---

3. 让脚本“无参也能跑”：给参数默认值

argparse 的目标并不是“只写 python hello.py 就能跑”。实际上关键在于：怎么设计参数。

3.1 位置参数变为可选（nargs + default）

import argparse

def main():
    # 1) 创建解析器对象
    parser = argparse.ArgumentParser(description="Say hello to someone.")
    # 2) 添加参数：位置参数，变为可选
    parser.add_argument("name", nargs="?", default="World", help="Name (default: World)")
    # 3) 解析命令行输入，得到 args 对象
    args = parser.parse_args()
    # 4) 使用解析结果
    print(f"Hello, {args.name}!")

if __name__ == "__main__":
    main()

现在：

• python hello.py → Hello, World!
• python hello.py Alice → Hello, Alice!

nargs：参数个数规则

• "?"：可有可无（适合位置参数可选化）

• "*"：可多个

• "+"：至少一个

3.2 使用可选参数 --name

import argparse

def main():
    # 1) 创建解析器对象
    parser = argparse.ArgumentParser(description="Say hello to someone.")
    # 2) 添加参数：可选参数
    parser.add_argument("--name", default="World", help="Name (default: World)")
    # 3) 解析命令行输入，得到 args 对象
    args = parser.parse_args()
    # 4) 使用解析结果
    print(f"Hello, {args.name}!")

if __name__ == "__main__":
    main()

现在：

• python hello.py → Hello, World!
• python hello.py --name Alice → Hello, Alice!

也可以写：

• "-n"
• 但 "--name" 可读性更强

---

4. 经典参数能力：type、default、required、choices、flag

# train.py
import argparse

def main():
    # 1) 创建解析器对象
    parser = argparse.ArgumentParser(description="A toy training script.")
    # 2) 添加参数：可选参数
    parser.add_argument("--epochs", type=int, default=10,
                        help="训练轮数（默认：10）")
    parser.add_argument("--lr", type=float, default=1e-3,
                        help="学习率（默认：1e-3）")
    parser.add_argument("--device", choices=["cpu", "cuda"], default="cpu",
                        help="运行设备：cpu/cuda（默认：cpu）")
    parser.add_argument("--verbose", action="store_true",
                        help="是否输出详细日志（加上该参数即为True）")
    # 3) 解析命令行输入，得到 args 对象
    args = parser.parse_args()
    # 4) 使用解析结果
    print("epochs =", args.epochs)
    print("lr     =", args.lr)
    print("device =", args.device)
    print("verbose=", args.verbose)

if __name__ == "__main__":
    main()

运行：

python train.py --epochs 20 --lr 0.001 --device cuda --verbose

要点总结：

• type=int/float：自动类型转换
• default=...：不提供就用默认值
• choices=[...]：限制合法取值，非法取值会报错并提示合法选项
• action="store_true"：布尔开关参数，有 --verbose 就打印更详细信息，否则不打印

---

5. 用 .sh 脚本批量运行多组参数（做实验对比非常常用）

.sh 是 Shell 脚本文件（通常在 Linux/macOS 或 Windows 的 WSL/Git Bash中使用）

用途：来把一堆命令写进文件，一键执行。

5.1 最简单：运行一次

创建 run_once.sh：

#!/usr/bin/env bash
python train.py --epochs 20 --lr 0.001 --device cpu

运行：

bash run_once.sh

（在 Linux/macOS 上也可以 chmod +x run_once.sh 后用 ./run_once.sh 运行。）

5.2 批量对比：循环跑多个参数组合

创建 grid_search.sh：

#!/usr/bin/env bash

for epochs in 10 20 50; do
  for lr in 0.001 0.0005; do
    echo "Running: epochs=$epochs lr=$lr"
    python train.py --epochs "$epochs" --lr "$lr" --device cpu
  done
done

也可以只打印将要执行的命令（不执行）：

#!/usr/bin/env bash

for epochs in 10 20 50
do
  for lr in 0.001 0.0005
  do
    echo python train.py --epochs "$epochs" --lr "$lr" --device cpu
  done
done

运行：

bash grid_search.sh

说明：

• epochs 和 lr 是 bash 变量
• "$epochs" 代表取出变量值并安全传入（推荐加引号）
  • bash 语法：$epochs 会被替换为变量 epochs 的值
• #!/usr/bin/env bash：shebang / hashbang，用 /usr/bin/env 去在 PATH环境变量里找到 bash
  • # (hash)
  • ! (bang)
  • 使用 bash grid_search.sh 运行脚本时，已经明确解释器是 bash，此时 shebang 不是必须的。

---

6. 最佳实践：让 argparse 结构更清晰

当参数变多时，推荐把 parser 单独封装：

import argparse

def build_parser():
    parser = argparse.ArgumentParser(description="My script.")
    parser.add_argument("--seed", type=int, default=0, help="随机种子")
    return parser

def main():
    parser = build_parser()
    args = parser.parse_args()
    print("seed =", args.seed)

if __name__ == "__main__":
    main()

这样主逻辑更干净、便于维护。

---

7. 你学会了什么？

• ArgumentParser(...)：创建命令行解析器
• add_argument(...)：定义参数规则（位置参数/可选参数）
• parse_args()：读取命令行并解析成 args.xxx
• --help 自动生成帮助信息，help= 可以写中文
• .sh 脚本可以一键批量跑多组参数，适合实验对比与复现实验