本文介绍如何将 Python 包封装为系统级可执行命令（如 django-admin），无需 python -m 前缀，通过独立脚本+PATH 配置实现全局调用。
本文介绍如何将 python 包封装为系统级可执行命令（如 `django-admin`），无需 `python -m` 前缀，通过独立脚本+path 配置实现全局调用。
要让自定义 Python 工具像 django-admin 一样直接在终端中运行（例如输入 utility-name --help 即可执行），核心在于：创建一个独立的、可执行的入口脚本，并将其所在目录加入操作系统的 PATH 环境变量。这与 python -m mypackage 的机制完全不同——后者依赖 Python 解释器显式调用，而前者是操作系统原生识别的命令。
✅ 步骤详解
1. 编写可执行入口脚本（无 .py 扩展名）
在项目根目录或专用 bin/ 目录下创建一个无扩展名的脚本文件（如 utility-name），内容如下：
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import sys
from utility_name.cli import main # 替换为你的实际模块路径，如 mypackage.cli.main
if __name__ == '__main__':
sys.exit(main())
⚠️ 注意事项：
- 第一行 #!/usr/bin/env python3 是 Unix/Linux/macOS 的 shebang，确保使用系统当前默认的 Python 3 解释器；
- Windows 用户可忽略 shebang，但需确保脚本以 .exe 或通过 py 启动器兼容（推荐统一用上述方式 + pip install 分发）；
- 脚本必须有执行权限（Linux/macOS）：chmod +x utility-name；
- 不要加 .py 后缀——否则系统会将其视为普通文本文件而非可执行命令。
2. 将脚本所在目录加入 PATH
-
Linux/macOS：将脚本放入 ~/.local/bin/（推荐），然后在 ~/.bashrc 或 ~/.zshrc 中添加：
export PATH="$HOME/.local/bin:$PATH"
执行 source ~/.bashrc 生效。
Windows：将脚本所在文件夹路径添加到系统环境变量 Path（可通过「系统属性 → 高级 → 环境变量」设置）。
3. （进阶推荐）通过 setuptools 自动安装（更专业、可分发）
在 setup.py 或 pyproject.toml 中声明 console_scripts 入口点，让 pip install -e . 自动创建可执行链接：
pyproject.toml 示例：
[project] name = "utility-name" version = "0.1.0" # ... [project.entry-points."console_scripts"] utility-name = "utility_name.cli:main" # 模块:函数
执行 pip install -e . 后，utility-name 命令将自动注册到 PATH（通常位于虚拟环境的 bin/ 或用户 site-packages 对应 bin 目录），完全复刻 Django 的发布体验。
? 补充说明
- django-admin 本质就是一个由 setuptools 自动生成的 shell 脚本（或 Windows .exe 包装器），它内部调用 django.core.management.execute_from_command_line()；
- 手动管理 PATH 适合开发调试；生产分发强烈建议使用 console_scripts，兼顾跨平台、可维护性与用户友好性；
- 若依赖特定 Python 环境（如虚拟环境），入口脚本中可显式激活或指定解释器路径（如 #!/path/to/venv/bin/python），但 console_scripts 方式会自动绑定当前安装环境，更可靠。
至此，你的 utility-name 就能像 django-admin、flask、poetry 一样，在任意目录下直接运行，真正成为“第一公民”级别的命令行工具。
