CLI Library for Python

构建出色的
命令行程序

Typer 是一个用于构建 CLI 的 Python 库，让用户喜欢使用、开发者喜欢创建。基于 Python 类型注解，编写轻松，到处补全。

快速开始 查看特性
基于 Python 类型注解
自动补全 · 全 Shell 支持
命令行界的 FastAPI
[ ~/project ] — zsh
main.py — typer
80×24
定位

Typer 是 FastAPI 的小兄弟， 它是命令行程序界的 FastAPI。

同样的设计哲学——类型注解驱动、自动文档、极简 API——从 Web API 延伸到了终端命令行。

主要特性

为什么选择 Typer

六大核心特性，让 CLI 开发从繁琐走向愉悦。

编写直观

出色的编辑器支持，到处都有补全。减少调试时间，专为易用、易学而设计。少花时间阅读文档。

# 输入 name，自动推断为必填参数
def main(name: str):
    print(f"Hello {name}")

使用方便

对最终用户来说非常易用。自动生成帮助信息，为所有 Shell 提供自动补全。

精简

最大限度减少代码重复。每个参数声明即可获得多项功能，更少 Bug。

起步简单

最简单的示例只需增加 2 行代码：

1 个 import + 1 次函数调用

规模可扩展

任意扩展复杂度，创建复杂的命令树和子命令组，支持选项和参数。

运行脚本

内置 typer 命令，可用于运行脚本，自动将其转换成 CLI 程序——即便脚本内部并未使用 Typer。

$ typer main.py run Camila → Hello Camila
安装

三秒安装，
即刻开始

创建并激活一个虚拟环境，然后安装 Typer。仅依赖少量小型库。

约 5 秒完成安装
bash
$ pip install typer
Collecting typer
Downloading typer-0.16.x-py3-none-any.whl
Collecting rich
Downloading rich-13.x-py3-none-any.whl
Collecting shellingham
Downloading shellingham-1.5.x-py2.py3-none-any.whl
---> 100%
Successfully installed typer rich shellingham
$ python -c "import typer; print(typer.__version__)"
0.16.x
# 安装完成，开始构建你的 CLI 🎉
快速开始

从最简示例到 你的第一个 CLI

只需标准的 Python 类型注解，Typer 会处理剩下的一切。

01

最简示例

创建 main.py，内容如下。这个脚本内部甚至没有使用 Typer。

main.py
def main(name: str):
    print(f"Hello {name}")
02

用 typer 命令运行

你可以用 typer 命令把它当作 CLI 程序来运行。

terminal
// 运行你的程序
$ typer main.py run
Missing argument 'name'.
// 自动获得 --help 帮助信息
$ typer main.py run --help
Usage: typer [PATH_OR_MODULE] run [OPTIONS] {name}
╭─ Arguments ──────────────────────╮
│ * name [required] │
╰──────────────────────────────────╯
// 传入 name 参数
$ typer main.py run Camila
Hello Camila
// 成功运行！🎉
03

在你的代码中使用 Typer

将 main.py 更新为以下内容，直接用 Python 运行。

main.py
import typer

def main(name: str):
    print(f"Hello {name}")

if __name__ == "__main__":
    typer.run(main)
04

直接用 Python 运行

现在你可以直接运行它，同样获得帮助信息和类型检查。

terminal
$ python main.py
Missing argument 'name'.
$ python main.py --help
Usage: main.py [OPTIONS] {name}
╭─ Arguments ──────────────────────╮
│ * name [required] │
╰──────────────────────────────────╯
$ python main.py Camila
Hello Camila
// 成功运行！🎉
进阶示例

多子命令与 自动补全

创建一个 Typer 应用，添加两个子命令，自动获得 --help 和 Shell 补全。

CODE

包含两个子命令

main.py
import typer

app = typer.Typer()

@app.command()
def hello(name: str):
    print(f"Hello {name}")

@app.command()
def goodbye(name: str, formal: bool = False):
    if formal:
        print(f"Goodbye Ms. {name}. Have a good day.")
    else:
        print(f"Bye {name}!")

if __name__ == "__main__":
    app()

显式创建 typer.Typer 应用，用 @app.command() 添加子命令。

RUN

运行与帮助信息

terminal
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
╭─ Commands ───────────────────────╮
│ hello │
│ goodbye │
╰──────────────────────────────────╯
// 免费获得 ✨ 自动补全 ✨
goodbye --help
Usage: main.py goodbye [OPTIONS] {name}
╭─ Options ────────────────────────╮
│ --formal --no-formal │
│ [default: no-formal] │
╰──────────────────────────────────╯
// bool 自动生成 --formal 和 --no-formal 🎉
terminal
$ python main.py hello Camila
Hello Camila
$ python main.py goodbye Camila
Bye Camila!
$ python main.py goodbye --formal Camila
Goodbye Ms. Camila. Have a good day.

注意：如果你的程序只有一个命令，默认情况下命令名在用法中会被省略：python main.py Camila。但当存在多个命令时，你必须显式地写上命令名：python main.py hello Camila。

小结

只需标准的 Python

你只需声明一次参数的类型——CLI 参数和 CLI 选项——将其作为函数参数即可。使用的是标准的现代 Python 类型，不需要学习新的语法、某个特定库的方法或类。

整数类型
total: int
布尔标志
force: bool
文件路径
path: Path
枚举选项
mode: Enum

同理也适用于文件、路径、枚举（选项）等，还提供了创建子命令组、添加元数据、额外校验等工具。

你将获得

出色的编辑器支持，包括无处不在的补全和类型检查。

你的用户将获得

安装你的包或使用 typer 命令时，终端（Bash、Zsh、Fish、PowerShell）中的自动 --help 帮助信息和自动补全。

查看完整教程 — 用户指南
依赖项

轻量依赖，精简至上

Typer 仅需要少量依赖（大多数都很小），保持你的项目干净。

rich

Rich

rich.readthedocs.io

用于自动显示格式美观的错误信息。

shell

Shellingham

github.com/sarugaku/shellingham

用于在安装补全时自动检测当前 Shell。

doc

Annotated Doc

github.com/fastapi/annotated-doc

用于从 Python 类型注解生成文档。

win

Colorama （仅 Windows）

github.com/tartley/colorama

用于在 Windows 上生成彩色终端文本。

关于 Click

Typer 过去依赖 Click。自 0.26.0 起，Typer 已将 Click 内置（vendored），统一了交互方式，便于未来维护。部分 Click 功能未来将不再可用。

关于 typer-slim

曾经有一个精简版 typer-slim。自 0.22.0 起已停止支持，现在只是安装完整的 Typer。如需全局禁用 Rich，设置 TYPER_USE_RICH=False。

开始构建你的
命令行程序

只需一行安装，两行代码起步。标准 Python 类型注解，自动补全，自动帮助信息。

阅读完整教程 GitHub 源码
install.sh
$ pip install typer
Successfully installed typer
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND...
# 就这么简单
本项目基于 MIT 许可证 授权
官方文档 · 源代码