从你的 Python 包创建 CLI 命令（快速指南）

Source: Dev.to

简而言之：在包的元数据中声明 console_scripts 入口点，激活目标虚拟环境，然后运行 pip install（开发时使用 pip install -e .）。这会在 ./venv/bin（Unix/macOS）或 venv\Scripts（Windows）中放置一个可执行包装脚本。

1) 示例项目结构

myproject/
├─ pyproject.toml   ← (or setup.cfg / setup.py)
└─ src/
   └─ cli.py

src/cli.py（示例）

def main():
    print("Hello from mycmd!")

if __name__ == "__main__":
    main()

入口点引用的函数（例如 mypackage.cli:main）将在已安装的命令被执行时调用。

2) 推荐使用：pyproject.toml + setuptools

使用 setuptools 作为构建后端时，添加如下 pyproject.toml：

[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.0.1"
description = "example package"

[project.scripts]
mycmd = "cli:main"

这会将 mycmd 设为已安装的命令，调用 cli:main。

3) 另一种常见方式：setup.cfg

如果项目使用 setup.cfg：

[metadata]
name = mypackage
version = 0.0.1

[options]
packages = find:

[options.entry_points]
console_scripts =
    mycmd = cli:main

（旧项目可能仍使用带有 entry_points={...} 的 setup.py。）

4) 安装到虚拟环境（先激活！）

Unix / macOS

python -m venv venv
source venv/bin/activate
pip install -e .

Windows (PowerShell)

python -m venv venv
venv\Scripts\Activate.ps1
pip install -e .

-e（editable）在开发期间非常方便，因为代码修改会立即在运行命令时生效。使用 pip install .（非 editable）同样会创建脚本/二进制文件，但会安装一个固定的构建版本。

5) 验证已安装的命令

Unix/macOS

which mycmd   # 若 venv 已激活，则显示 venv/bin/mycmd
mycmd         # 运行并检查输出

预期位置

• Unix/macOS: ./venv/bin/mycmd（可执行包装脚本）
• Windows: venv\Scripts\mycmd.exe（或 mycmd-script.py）

运行 mycmd 应显示 Hello from mycmd!（或 main() 打印的任何内容）。

6) 注意事项与最佳实践

• 在 pip install 前务必激活虚拟环境，除非你明确想进行系统/全局安装。
• console_scripts（入口点）是推荐的做法——它们会生成适合操作系统的包装脚本，并与包元数据集成。
• 传统的 setup.py 中的 scripts= 选项会直接复制脚本；相较之下，入口点在依赖解析和跨平台行为上更优。
• 像 Click 或 Typer 这样的库可以让构建更丰富的 CLI 应用变得简单；入口点语法保持不变（指向调用 CLI 的函数）。