子命令 help 不显示是因为 add_parser() 未传 help 参数；需为每个子命令显式指定 help=字符串以控制汇总页说明，再用 description 和 RawDescriptionHelpFormatter 定制详情页格式。

子命令 help 描述不显示？检查 help 参数是否传给了 add_parser()

默认情况下，add_subparsers() 创建的子命令解析器不会自动显示描述，除非你在调用 add_parser() 时显式传入 help= 字符串。很多人只给子命令设置了 description 或 epilog，但这些不影响 --help 汇总页里的那一行简短说明。

正确做法是：

• subparsers = parser.add_subparsers(dest="command")
• sub_a = subparsers.add_parser("train", help="训练模型（支持 CPU/GPU）") ← 这个 help 才控制汇总页显示
• sub_a.add_argument("--lr", type=float, default=1e-3)

想让子命令详情页也更友好？用 description 和 formatter_class

子命令自身的 --help（比如运行 python script.py train --help）默认只显示参数，不带顶层描述。要让它显示说明文字，得在 add_parser() 里加 description：

sub_a = subparsers.add_parser(
    "train",
    help="训练模型（支持 CPU/GPU）",
    description="使用指定数据集和超参训练深度学习模型，支持断点续训。",
    formatter_class=argparse.RawDescriptionHelpFormatter
)

注意：RawDescriptionHelpFormatter 能保留换行和缩进，否则多行 description 会被压成一行。

避免 help 文本被截断或重复？别在 add_subparsers() 里设 help

add_subparsers() 本身不接受 help 参数 —— 如果你强行写了，argparse 会静默忽略，还可能触发 TypeError: add_subparsers() got an unexpected keyword argument 'help'（取决于 Python 版本）。

常见误写：

# ❌ 错误：add_subparsers 不吃 help 参数
subparsers = parser.add_subparsers(help="可用操作", dest="command")
✅ 正确：help 只属于每个子解析器
subparsers = parser.add_subparsers(dest="command")

中文 help 显示乱码？确认终端和 Python 文件编码

如果 help 字符串含中文但在终端里显示为 或空格，问题通常不在 argparse，而在环境：

• Python 源文件开头没加 # -*- coding: utf-8 -*-
• Windows cmd 默认编码是 gbk，而 Python 3.7+ 的 argpar

  

  se 内部用 utf-8 渲染 help —— 此时需设置环境变量 chcp 65001 或改用 Windows Terminal / WSL
• IDE（如 PyCharm）终端编码设置不是 UTF-8

验证方式：打印 sys.stdout.encoding，它应为 utf-8；如果不是，help 中文基本注定显示异常。

子命令 help 的定制关键就两点：每个 add_parser() 必须带 help=，且描述性文字要靠 description + 合适的 formatter_class 控制格式。漏掉前者，汇总页就空着；忽略后者，子命令详情页就干巴巴。