Python 环境与包管理指南
整理自对话讨论，涵盖
pip/pipx/uv/venv的分工与实操命令，适用于日常开发（含TaxEngine税务计算脚本、pdf2zhPDF 翻译工具、yt-dlp等命令行工具的环境管理）。
一、先搞清楚：你装的是"库"还是"工具"
在动手之前，先问自己一个问题：
这个东西是要在代码里
import用的库，还是要在终端直接敲命令用的工具？
这个判断决定了你该用哪套方案：
| 类型 | 举例 | 推荐方案 |
|---|---|---|
代码里 import 的库 | pandas、requests、openpyxl | venv + pip（或 uv venv） |
| 终端直接敲命令的工具 | yt-dlp、pdf2zh、black | pipx（或 uv tool） |
二、四个工具的角色分工
| 工具 | 管理对象 | 是否隔离环境 | 是否管理 Python 版本 | 硬盘占用 |
|---|---|---|---|---|
| pip | 当前激活环境里的库 | 否（装进当前环境） | 否 | — |
| venv | 项目专属虚拟环境 | 是（每项目一个） | 否（复用系统版本） | 较省 |
| pipx | 命令行工具 | 是（每工具一个独立环境） | 否（复用系统版本） | 较省 |
| uv | 库 / 项目环境 / 命令行工具 / Python 版本 | 是 | 是（可自动下载指定版本） | 较大（每个 Python 版本都要占空间） |
一句话总结分工逻辑：
pip不能单独用，必须配合venv隔离，否则容易"依赖地狱"（不同项目互相打架）pipx专门伺候命令行工具，默认优先选它uv是全能替代品，速度快、还能自动管理 Python 版本，遇到工具对 Python 版本有硬性要求、且和系统默认版本不匹配时（比如pdf2zh需要 3.10–3.12），才切换用它
三、场景一：命令行工具（终端直接敲命令）
默认用 pipx
pipx install <工具名>
- 每个工具自动获得独立虚拟环境，互不冲突
- 复用系统已有的 Python，比较省硬盘
- 装完直接全局可用，任意目录都能敲命令
例外：工具对 Python 版本有硬性要求 → 换 uv
比如 pdf2zh（PDF 翻译工具）要求 Python 3.10–3.12，但系统默认是 3.14：
# uv 会自动下载所需版本的 Python，不需要你自己先装
uv tool install --python 3.12 pdf2zh
代价是会多占一些硬盘空间（下载对应版本的 Python 解释器）。
用 pipx 配合手动指定版本也可以（不想装 uv 的话）
# 先用 Homebrew 装好 3.12
brew install [email protected]
# 确认路径
which python3.12
# 用 pipx 指定版本装
pipx install pdf2zh --python /usr/local/bin/python3.12
判断口诀：默认 pipx，遇到版本报错才为那一个工具单独用 uv，其他工具继续用 pipx，两套工具链可以共存，互不影响。
四、场景二：项目里的库依赖（import 用）
标准三步走：venv + pip
1. 创建虚拟环境
进入项目目录，运行：
# 第一个 venv 是工具名，第二个 venv 是环境文件夹名（也可以叫 .venv）
python3 -m venv venv
运行完会在项目目录下多出一个 venv/ 文件夹。
2. 激活虚拟环境（最重要的一步）
| 操作系统 | 激活命令（在项目根目录运行） |
|---|---|
| Windows (CMD) | venv\Scripts\activate |
| Windows (PowerShell) | .\venv\Scripts\Activate.ps1 |
| macOS / Linux | source venv/bin/activate |
激活成功的标志： 命令行提示符前面会出现 (venv) 字样。
3. 安装库并运行脚本
激活后，pip install 装的东西只会留在这个"小房间"里，不会污染系统全局环境：
pip install pandas requests openpyxl
python your_script.py
用完退出：
deactivate
用 uv 替代 venv + pip（更快，语法更简洁）
功能完全等价，但速度快很多（Rust 编写，比 pip 快 10–100 倍）：
cd 你的项目目录
uv venv # 生成 .venv
source .venv/bin/activate # 激活方式跟 venv 一致
uv pip install pandas requests # 装库
注意：
uv venv依然是"在项目目录下运行"的逻辑，跟传统 venv 一样按项目隔离，不是全局通用的方案。真正"不限目录、随处可用"的是uv tool install（针对命令行工具，见第三节），两者不要混淆。
五、常用进阶操作（venv 通用）
# 退出环境
deactivate
# 导出依赖清单（方便别人一键复现你的环境，或者你换机器时用）
pip freeze > requirements.txt
# 一键恢复环境
pip install -r requirements.txt
避坑指南： 如果项目用 Git 管理，记得在 .gitignore 里加上 venv/（或 .venv/），几百 MB 的环境文件夹不应该传到 GitHub 上。
六、决策速查表
| 你要做的事 | 推荐方案 | 命令 |
|---|---|---|
| 装终端命令行工具 | pipx | pipx install <工具> |
| 命令行工具但对 Python 版本有硬性要求 | uv | uv tool install --python 3.12 <工具> |
| 项目里写代码要用的库 | venv + pip | python3 -m venv venv && pip install <库> |
| 想要更快的 venv+pip 替代品 | uv | uv venv && uv pip install <库> |
七、当前工具归类参考
| 工具 / 脚本 | 类型 | 推荐方案 | 备注 |
|---|---|---|---|
yt-dlp | 命令行工具 | pipx（现状已经是对的，不用动） | 对 Python 版本无严格要求，装的频率也不高，没必要换 uv |
pdf2zh（PDF 翻译） | 命令行工具，但版本要求特殊 | uv | 系统默认 Python 3.14，超出 pdf2zh 要求的 3.10–3.12，需要 uv tool install --python 3.12 pdf2zh |
TaxEngine 税务计算脚本 / Wise 相关脚本 | 项目库依赖 | venv + pip（或 uv venv 替代） | 用到 pandas 等库，应绑定在项目专属虚拟环境里，避免以后装其他工具时把依赖搅乱 |
针对 TaxEngine / Wise 脚本的具体操作流程
# 1. 进入代码目录
cd 你的TaxEngine项目目录
# 2. 创建虚拟环境
python3 -m venv venv
# 3. 激活环境
source venv/bin/activate # macOS/Linux
# 4. 安装依赖
pip install pandas
# 5. 运行脚本
python wise_calc.py -f my_data.csv
# 用完退出
deactivate
如果之后想提速，可以把第 2–4 步替换成 uv 版本：
uv venv
source .venv/bin/activate
uv pip install pandas
八、一图记忆
装的是命令行工具吗？
├─ 是 → 对 Python 版本有要求吗？
│ ├─ 否 → pipx install <工具>
│ └─ 是 → uv tool install --python <版本> <工具>
│
└─ 否（是项目里 import 的库）→ 在项目目录下：
venv + pip（标准）或 uv venv + uv pip（更快）