如何正确分发依赖自定义包的Python脚本，兼顾系统级可用与虚拟环境规范？

一、核心配置：用pyproject.toml绑定脚本与依赖 #

通过setuptools的[project.scripts]字段，你可以把包内的入口函数映射为终端可执行命令，同时自动拉取依赖的自定义包。典型配置示例：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.1.0"
dependencies = [
    "your-custom-package>=1.0.0",  # 自动安装依赖的自定义包
]

[project.scripts]
my-script = "mypackage.cli:main"  # 终端命令名 → 包内入口函数路径

这里的my-script是最终在终端运行的命令，mypackage.cli:main指向你包内cli.py文件里的main()函数（脚本逻辑的入口）。

二、协调虚拟环境与系统级调用的实用方案 #

1. 用pipx实现隔离安装+全局可访问 #

这是最省心的方案，pipx专门为Python CLI工具设计：它会自动为每个工具创建独立虚拟环境，同时把脚本链接到系统PATH目录（如~/.local/bin或/usr/local/bin），无需管理员权限就能全局调用，完全隔离系统Python环境。

• 安装pipx：Debian/Ubuntu用sudo apt install pipx，其他系统用pip install --user pipx
• 安装你的包：本地包用pipx install ./path-to-your-package，上传到PyPI的包用pipx install mypackage
• 之后直接在终端输入my-script即可运行，所有依赖都在独立环境里，不会污染系统。

2. 手动创建虚拟环境+软链脚本 #

如果不想用pipx，可以手动搭建隔离环境并链接脚本：

• 创建并配置虚拟环境：python -m venv /opt/mypackage-venv
• 安装包到虚拟环境：/opt/mypackage-venv/bin/pip install ./path-to-your-package
• 软链脚本到系统可执行目录：sudo ln -s /opt/mypackage-venv/bin/my-script /usr/local/bin/my-script
  运行my-script时，会自动调用虚拟环境里的Python和依赖，完全不影响系统环境。

3. 给单脚本指定虚拟环境Python（适合非包形式脚本） #

如果只是单个独立脚本，不是完整包，可以在脚本开头加shebang指定虚拟环境的Python路径：

#!/opt/mypackage-venv/bin/python
# 以下是你的脚本逻辑

给脚本加执行权限：chmod +x myscript.py，再软链到系统目录：sudo ln -s ./myscript.py /usr/local/bin/my-script。但这种方式需要手动管理依赖，不如包形式的配置灵活。

三、为什么不直接用sudo pip install？ #

现在Linux系统的默认Python是系统关键组件的依赖，直接用sudo pip安装包会污染系统Python环境，极易引发系统工具的依赖冲突，官方和社区都强烈不推荐这种做法。上面的方案既满足了脚本全局调用的需求，又遵守了虚拟环境隔离的最佳实践。

内容的提问来源于stack exchange，提问作者loqueelviento