Python-08-虚拟环境与包管理
这篇讲什么
这一篇解决的是工程问题而不是语法问题:为什么
pip install会把你昨天的项目搞崩、虚拟环境到底改了哪几个变量、requirements.txt该不该锁版本、uv/poetry/pdm该选哪个、依赖冲突怎么排查、自己的库怎么发到 PyPI。这些都是「没人教但迟早要踩」的内容。踩过一次全局依赖冲突的人,才会真正理解虚拟环境的价值——但那一次往往要花掉一整天。
一、是什么:三层概念要分清
| 概念 | 是什么 | 例子 |
|---|---|---|
| 虚拟环境(Virtual Environment) | 一个目录,里面放独立的解释器入口与独立的 site-packages | .venv/ |
| 包管理器(Package Manager) | 负责下载、解析、安装、卸载包的客户端 | pip、uv |
| 依赖声明文件 | 描述「这个项目需要哪些包」的元数据 | pyproject.toml、requirements.txt |
记住一句话
虚拟环境解决「装到哪儿」,包管理器解决「怎么装」,声明文件解决「装什么版本」。
三者是正交的:你可以用
pip+requirements.txt,也可以用uv+pyproject.toml,组合自由。
二、为什么需要虚拟环境
2.1 一个真实会发生的场景
假设你在同一个 Python 解释器里做两个项目:
项目 A(老系统维护) 需要 requests==2.25.0 → 它要求 urllib3<1.27
项目 B(新功能开发) 需要 requests>=2.31 → 它要求 urllib3>=1.26,<3
由于两者共用 C:\Python312\Lib\site-packages,后装的会覆盖先装的:
# 没有虚拟环境时的操作序列
pip install requests==2.25.0 # 项目 A 正常
pip install requests==2.31.0 # 项目 B 正常,但项目 A 挂了
# 项目 A 再跑一次,会看到运行时错误而不是安装错误:
# ImportError: cannot import name 'DEFAULT_CIPHERS' from 'urllib3.util.ssl_'
这类故障的三个特征
1. 不报安装错误——
pip install只看包本身能不能装,不关心你其他项目是否需要旧版本;2. 故障出现在别的项目里——你刚改的是 B,坏掉的是 A,因果链被时间隔开了;
3. 无法靠重装某一方根治——A 和 B 的需求在同一个空间里本质冲突,只能二选一。
唯一彻底的解法就是让 A 和 B 各自拥有独立的
site-packages,这正是虚拟环境做的事。
2.2 除了版本冲突,还有三个理由
| 理由 | 说明 |
|---|---|
| 环境可复现 | requirements.txt / uv.lock 保证同事和 CI 装出同样的版本组合 |
| 不污染系统 | 系统 Python(Linux 上尤其明显)被发行版工具依赖,装坏可能导致系统工具失效 |
| 环境可丢弃 | 依赖装乱了直接 rm -rf .venv && python -m venv .venv 重建,成本以秒计 |
现代 Linux 发行版的强制要求
Debian/Ubuntu 较新版本的系统 Python 启用了 PEP 668 的「外部管理环境」保护,
直接
pip install到系统环境会报error: externally-managed-environment。这不是 bug,而是发行版在逼你使用虚拟环境。
三、venv:创建与激活
3.1 创建
venv 是标准库模块(PEP 405),无需安装:
# 在项目根目录创建名为 .venv 的虚拟环境
python -m venv .venv
# 常用选项
python -m venv --system-site-packages .venv # 允许看到全局包(少数场景有用,但会重新引入冲突)
python -m venv --without-pip .venv # 不装 pip,用于离线或自举场景
python -m venv --prompt myproj .venv # 自定义激活后的提示符前缀
为什么用
python -m venv而不是python -m virtualenv-
venv是标准库自带,任何 Python 3.3+ 都能用,不依赖网络;- 第三方
virtualenv创建速度更快、支持更老的 Python 版本,在需要极速创建大量环境时仍有价值;- 新项目优先
venv,它够用且零依赖。若你的工具链已经用uv,则用uv venv(速度最快)。
3.2 激活:Windows 与 macOS/Linux 的差异
| 平台 | Shell | 激活命令 |
|---|---|---|
| Windows | PowerShell | .venv\Scripts\Activate.ps1 |
| Windows | cmd.exe | .venv\Scripts\activate.bat |
| Windows | Git Bash | source .venv/Scripts/activate |
| macOS / Linux | bash / zsh | source .venv/bin/activate |
| macOS / Linux | fish | source .venv/bin/activate.fish |
| macOS / Linux | csh / tcsh | source .venv/bin/activate.csh |
# Windows PowerShell:若提示「禁止运行脚本」,需要为当前用户放开策略
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# 激活成功后提示符会变成 (.venv) 开头
(.venv) PS D:\proj> python -c "import sys; print(sys.prefix)"
# 退出虚拟环境(各平台通用,它是个 shell 函数)
deactivate
其实可以不激活
激活只是把
.venv的bin/Scripts目录临时加到PATH前面,没有魔法。在脚本、CI、Makefile 里更稳妥的写法是直接用虚拟环境里的解释器绝对路径:
```bash
.venv/Scripts/python.exe -m pip install -r requirements.txt # Windows
.venv/bin/python -m pip install -r requirements.txt # macOS / Linux
```
这样不依赖当前 shell 的状态,也不会出现「以为激活了其实没有」。
3.3 手工验证自己是否在虚拟环境里
import os
import sys
import sysconfig
def describe_environment() -> None:
"""打印当前解释器的环境关键信息——排查「装到哪儿去了」的第一手段。"""
prefix, base_prefix = sys.prefix, sys.base_prefix
print("可执行文件 :", sys.executable)
print("sys.prefix :", prefix)
print("sys.base_prefix :", base_prefix)
# 判断依据:在虚拟环境里 sys.prefix 指向 venv 目录,而 base_prefix 仍指向真实解释器
print("是否在虚拟环境 :", prefix != base_prefix)
print("site-packages :", sysconfig.get_paths()["purelib"])
print("VIRTUAL_ENV :", os.environ.get("VIRTUAL_ENV", "(未激活)"))
print("sys.path 前三项 :")
for entry in sys.path[:3]:
print(" ", entry)
if __name__ == "__main__":
describe_environment()
未激活时你会看到 sys.prefix == sys.base_prefix;激活后两者分离:
sys.prefix : C:\proj\.venv
sys.base_prefix : C:\Python312
是否在虚拟环境 : True
四、虚拟环境的目录结构与原理
4.1 目录结构
.venv/
├── pyvenv.cfg ← 唯一的「配置」文件,记录它是从哪个解释器创建的
├── Scripts/ ← Windows:可执行文件与激活脚本
│ ├── python.exe ← 其实是原解释器的副本(或符号链接)
│ ├── pip.exe pip3.exe ← 控制台脚本入口(*.exe 由 pip 生成)
│ ├── activate activate.bat Activate.ps1 deactivate.bat
│ └── ...
├── Lib/
│ └── site-packages/ ← 该环境专属的第三方包装在这里
└── Include/ ← C 扩展头文件(用不上时可忽略)
# macOS / Linux 对应结构:
# .venv/bin/python .venv/bin/activate .venv/lib/python3.12/site-packages/
4.2 pyvenv.cfg 长什么样
实测创建一个环境后,该文件的内容是:
home = C:\Python312
include-system-site-packages = false
version = 3.12.14
executable = C:\Python312\python.exe
command = C:\Python312\python.exe -m venv --without-pip C:\proj\.venv
| 键 | 作用 |
|---|---|
home | 真实解释器所在目录,site 模块据此找到标准库 |
include-system-site-packages | 是否能看到全局 site-packages;对应 --system-site-packages |
version | 创建时的 Python 版本,用于诊断「venv 与解释器版本不匹配」 |
executable / command | 记录原始解释器路径与创建命令,便于复现 |
import pathlib
import sys
def show_pyvenv_cfg() -> None:
"""读 pyvenv.cfg:判断环境是否包含全局包、由谁创建的最快方式。"""
cfg = pathlib.Path(sys.prefix) / "pyvenv.cfg"
if not cfg.exists():
print("当前不在虚拟环境中(没有 pyvenv.cfg)")
return
print(f"--- {cfg} ---")
print(cfg.read_text(encoding="utf-8").strip())
for line in cfg.read_text(encoding="utf-8").splitlines():
if line.startswith("include-system-site-packages"):
enabled = line.split("=", 1)[1].strip().lower() == "true"
print("能看到全局包(冲突风险更高)" if enabled else "与全局包隔离(推荐)")
if __name__ == "__main__":
show_pyvenv_cfg()
4.3 原理:虚拟环境没有复制解释器
关键认知
venv不复制一整套标准库,它只创建入口并把「环境根目录」往下移一层。所谓激活,实际上改了四样东西:
1.
PATH:把.venv/Scripts(或bin)插到最前;2.
VIRTUAL_ENV:设置环境变量,供工具识别当前环境;3.
sys.prefix/sys.exec_prefix:指向.venv而非真实安装目录;4.
sys.path:把.venv/Lib/site-packages插到sys.path靠前的位置。于是
import时先命中虚拟环境里的包,标准库仍从base_prefix加载——既隔离又省空间。
五、pip 常用命令
# 查看与自升级(永远推荐 python -m pip 形式,见注意事项)
python -m pip --version
python -m pip install --upgrade pip
# 安装
python -m pip install requests # 最新版
python -m pip install "requests==2.31.0" # 精确版本(必须有引号,见坑 3)
python -m pip install "requests>=2.28,<3" # 版本区间
python -m pip install -r requirements.txt # 按依赖文件批量安装
python -m pip install -e . # 可编辑安装当前项目(开发库时常用)
python -m pip install --no-deps requests # 只装自己,不解析依赖(排障用)
python -m pip install --dry-run requests # 只解析不安装,看会装哪些东西
# 卸载与升级
python -m pip uninstall requests
python -m pip install --upgrade requests
python -m pip list --outdated # 列出有新版本的包
# 查看
python -m pip list # 表格形式
python -m pip list --format=freeze # 等价于 freeze 的格式
python -m pip show requests # 详情:版本、位置、依赖、被谁依赖
python -m pip freeze # 导出当前环境(唯一真实来源)
python -m pip check # 检查依赖一致性
实测的 pip show 输出格式(字段含义值得记牢):
Name: requests
Version: 2.34.2
Summary: Python HTTP for Humans.
License: Apache-2.0
Location: C:\proj\.venv\Lib\site-packages ← 装到哪儿了,排查问题的关键字段
Requires: certifi, charset_normalizer, idna, urllib3 ← 它依赖谁
Required-by: ← 谁依赖它(空表示没人依赖)
为什么强调
python -m pip而不是pip直接敲
pip依赖PATH里的顺序。如果虚拟环境没激活、或者 PATH 里有多个 Python,你很可能把包装到了另一个解释器里,然后对着「明明装了却 import 不到」困惑半天。
python -m pip用当前正在使用的解释器执行 pip,目标与你的代码一致,不存在歧义。
六、requirements.txt:写法与版本锁定
6.1 版本约束运算符
# requirements.txt —— 每行一个需求
requests==2.31.0 # 精确锁定:完全确定,但永不自动拿到安全修复
urllib3>=2.0,<3 # 范围:兼容性与修复补丁都拿得到
click~=8.1.7 # 兼容版本:等价于 >=8.1.7, ==8.1.*,只允许最后一位变
flask!=2.3.0 # 排除特定版本(该版本有已知 bug 时非常有用)
numpy # 不写约束 = 任意版本,仅适合一次性脚本
pandas>=2.0 ; python_version >= "3.10" # 环境标记:只在指定条件下安装
pywin32>=306 ; sys_platform == "win32" # 平台标记:Windows 才装
-r base.txt # 引用另一个文件(分层管理依赖)
-e ./libs/mylib # 以可编辑模式安装本地包
--index-url https://pypi.tuna.tsinghua.edu.cn/simple # 可把源写进文件
| 运算符 | 含义 | 适用 |
|---|---|---|
==2.31.0 | 精确版本 | 应用部署(要可复现) |
>=2.0,<3 | 范围 | 库的依赖声明(要给使用者留余地) |
~=8.1.7 | 兼容发布(>=8.1.7, ==8.1.*) | 想自动拿补丁但不想要新功能 |
!=2.3.0 | 排除 | 规避已知问题版本 |
6.2 分层管理:requirements.txt 与 requirements-dev.txt
# requirements.txt —— 运行时依赖,部署机器上都要装
requests==2.31.0
flask==3.0.0
# requirements-dev.txt —— 只在开发与 CI 装
-r requirements.txt
pytest==7.4.0
ruff==0.1.0
mypy==1.7.0
为什么要分层
生产镜像只需要运行时依赖。把
pytest、mypy也装进生产环境,会让镜像变大、攻击面变宽、冷启动变慢。
-r requirements.txt让 dev 文件自动包含运行时依赖,避免两处维护。
6.3 锁版本的必要性
问题:requirements.txt 写 requests>=2.28
今天装到 2.31.0,测试通过并上线
三个月后 CI 重新构建,装到 2.34.2,行为变了 → 构建成功但线上故障
锁定的对象是「间接依赖」,不只是直接依赖
真正让构建不可复现的,往往不是你写的那 10 个直接依赖,而是它们拖进来的几十个传递依赖。
pip freeze会把这些全部固定下来,这正是它最大的价值——牺牲可读性换取可复现性。
6.4 pip freeze 的局限
# 它会连 pip 自己也输出(视 pip 版本与安装方式而定),且顺序不保证
python -m pip freeze > requirements.txt
| 局限 | 具体表现 | 对策 |
|---|---|---|
| 混入不该发布的包 | 把 pytest、本地 -e 路径、甚至 pip 自身都写进去 | 用分层文件,或改用 uv export / poetry export |
| 只能看到「已安装」 | 它不区分直接依赖与传递依赖,读的人无法判断哪个能删 | 用 uv tree / poetry show --tree 查看依赖树 |
| 不含环境标记 | 在 Windows 导出的文件可能在没有 pywin32 的 Linux 上失败 | 手工补 ; sys_platform == "win32" 标记 |
| 不含哈希 | 无法校验下载内容是否被篡改 | 用 pip-compile --generate-hashes(pip-tools)或 uv lock |
| 与项目元数据脱节 | 项目需要什么(pyproject.toml)和实际装了什么(freeze)可能不一致 | 用 uv/poetry 从元数据生成锁文件 |
推荐的现代分工
- 应用 / 服务:用锁文件(
uv.lock、poetry.lock)保证部署可复现;- 要发布的库:
pyproject.toml里写宽范围依赖(requests>=2.28),不要提交锁文件,否则会强迫下游接受你的版本选择。
七、pyproject.toml 与 PEP 621
pyproject.toml 是 PEP 518 引入的统一配置文件,PEP 621 标准化了其中的 [project] 表。它是现代 Python 项目的事实中心:构建配置、依赖声明、工具配置(ruff/mypy/pytest)都收敛到这一个文件。
# pyproject.toml
[build-system]
# 声明「用什么来构建这个项目」,构建前端(pip、uv)会先装这些依赖
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-tool" # 发布到 PyPI 的唯一标识,全局不得重名
version = "0.1.0" # 也可写成 dynamic,由构建后端从别处读取
description = "一个示例工具库"
readme = "README.md" # 会作为 PyPI 页面正文
requires-python = ">=3.9" # 关键:pip 会据此拒绝在不兼容的解释器上安装
license = { text = "MIT" } # 新写法见 PEP 639,以官方最新文档为准
authors = [{ name = "Your Name", email = "you@example.com" }]
keywords = ["cli", "tool"]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
]
dependencies = [ # 运行时依赖,范围要宽(这是给下游的承诺)
"requests>=2.28",
"click>=8.0",
]
[project.optional-dependencies] # 可选依赖:pip install "my-tool[dev]"
dev = ["pytest>=7.0", "ruff>=0.1"]
docs = ["sphinx>=7.0"]
[project.scripts] # 安装后生成命令行入口 my-tool
my-tool = "my_tool.cli:main"
[project.urls]
Homepage = "https://github.com/you/my-tool"
# 以下工具配置放在同一个文件里,避免根目录散落 .ruff.toml / mypy.ini / setup.cfg
[tool.ruff]
line-length = 100
[tool.mypy]
strict = true
[tool.pytest.ini_options]
testpaths = ["tests"]
import tomllib # Python 3.11+ 标准库;3.10 及更早用第三方 tomli
with open("pyproject.toml", "rb") as fh: # tomllib 要求二进制模式
config = tomllib.load(fh)
proj = config["project"]
print("包名 :", proj["name"])
print("运行时依赖 :", proj["dependencies"])
print("可选依赖 dev:", proj["optional-dependencies"]["dev"])
print("命令入口 :", proj["scripts"])
print("构建后端 :", config["build-system"]["build-backend"])
用
python -m build而不是pip install build之外的旧命令
setup.py仍能工作,但 PEP 517/518 之后推荐用声明式配置 + 构建前端:项目只声明「用什么后端」,具体构建由
build/pip/uv在隔离环境中执行。这消除了「构建依赖装在自己环境里」的经典污染问题。
八、现代工具链:uv、poetry、pdm
| 维度 | uv | poetry | pdm |
|---|---|---|---|
| 开发方 | Astral(Ruff 团队) | Poetry 社区 | PDM 社区 |
| 实现语言 | Rust | Python | Python |
| 定位 | 极速的一体化替代(pip/venv/pipx/锁) | 面向「应用与库」的完整项目管理 | 遵循 PEP 标准的现代项目管理 |
| 配置文件 | 标准 pyproject.toml(PEP 621) | 自有 [tool.poetry] 表(新版也支持 PEP 621) | 标准 pyproject.toml(PEP 621) |
| 锁文件 | uv.lock | poetry.lock | pdm.lock |
| 虚拟环境 | 自动管理(也可 --system) | 默认自动创建并管理 | 默认 .venv(PEP 582 风格可选) |
| 依赖解析速度 | 极快(Rust,常以数量级领先) | 中等 | 中等 |
| 能否装任意 Python 版本 | 能(uv python install 3.12) | 不能(需自行安装) | 不能 |
| 兼容 pip 生态 | 高(uv pip 子命令可直接替代) | 自有一套命令 | 高(含 pdm export 等) |
| 学习成本 | 低(uv pip 几乎无缝迁移) | 中(自有命令体系) | 中 |
| 适合 | 想统一工具链、追求速度的新老项目 | 习惯 Poetry 工作流、需要成熟发布流程 | 想严格跟随 PEP 标准、需要灵活后端 |
# ---------- uv:最常见的三条路径 ----------
# ① 完全替代 pip/venv,迁移成本最低
uv venv # 创建 .venv(比 python -m venv 快得多)
uv pip install -r requirements.txt # 接口与 pip 一致,只是快
# ② 用项目管理模式(推荐新项目)
uv init myproj && cd myproj
uv add requests # 装包并写入 pyproject.toml + uv.lock
uv add --dev pytest
uv run python main.py # 自动用项目的环境运行,无需手动激活
uv sync # 按 uv.lock 精确还原环境(CI 用这个)
uv python install 3.12 # 连解释器版本也交给它管
# ---------- poetry ----------
poetry new myproj && cd myproj
poetry add requests # 写入 pyproject.toml 并更新 poetry.lock
poetry add --group dev pytest
poetry install # 按 lock 安装
poetry run python main.py
poetry build && poetry publish # 构建与发布一体化
# ---------- pdm ----------
pdm init && pdm add requests
pdm install
pdm run python main.py
pdm export -o requirements.txt # 导出给不使用 pdm 的环境
怎么选
- 已经有成熟 Poetry 流程的团队:不必为了速度迁移,收益不等于迁移成本。
- 新项目 / 个人项目 / 想统一工具链:直接用
uv,它同时覆盖pip、venv、pipx、pip-tools的角色。- 严格跟随 PEP 标准、需要多后端灵活切换:
pdm。- 三者功能高度重叠,不要在一个项目里混用,锁文件与命令体系会互相打架。
以上工具的 CLI 与特性迭代很快,以官方最新文档为准。
九、离线安装与镜像源配置
9.1 换国内镜像源
# 方式一:临时指定(一次有效)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests
# 方式二:写入用户级配置,永久生效(推荐)
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn # 旧版 pip 遇证书问题时可加
pip config list # 查看当前生效配置
pip config debug # 查看配置文件位置与取值来源
# 方式三:环境变量(容器/CI 里最方便,不用改文件)
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # macOS / Linux
$env:PIP_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple" # Windows PowerShell
常用镜像地址:
| 提供方 | index-url |
|---|---|
| 清华大学 TUNA | https://pypi.tuna.tsinghua.edu.cn/simple |
| 阿里云 | https://mirrors.aliyun.com/pypi/simple/ |
| 腾讯云 | https://mirrors.cloud.tencent.com/pypi/simple/ |
| 中科大 USTC | https://pypi.mirrors.ustc.edu.cn/simple/ |
index-url与extra-index-url不要混用出安全问题-
index-url:替换主源;-
extra-index-url:追加备用源,pip 会在所有源里挑「版本最高」的那个。混用官方源 + 私有源时,若私有包名与 PyPI 上的某个包同名,pip 可能装到公共源上的同名恶意包(依赖混淆攻击)。
正确做法是用
--index-url指向私有源并配置上游代理,而不是简单追加。
9.2 离线安装
# ① 在有网机器上把包和依赖一起下载成 whl 文件
pip download requests -d ./wheels # 含全部依赖
pip download -r requirements.txt -d ./wheels # 按需求文件下载
pip download --only-binary=:all: -r requirements.txt -d ./wheels # 只要 wheel,避免离线机器上没有编译器
# ② 把 wheels 目录拷到离线机器(U 盘 / 内网制品库),然后
pip install --no-index --find-links=./wheels requests
pip install --no-index --find-links=./wheels -r requirements.txt
| 参数 | 作用 |
|---|---|
--no-index | 完全不访问网络索引,杜绝偷偷联网导致的超时等待 |
--find-links=./wheels | 从本地目录(而不是索引)查找包 |
--only-binary=:all: | 强制只下载预编译 wheel,避免目标机器上构建失败 |
--no-deps | 只装指定包,不解析依赖(依赖已手工备齐时才用) |
离线环境的三个前提
1. 平台必须一致:Windows 上下的
cp312-win_amd64.whl在 Linux 上装不了;2. Python 版本必须一致:
cp312的 wheel 不能用于 3.11;3. 纯 Python 包(
py3-none-any)才跨平台,带 C 扩展的包必须按目标平台下载。稳妥做法是在与生产完全相同的容器/系统里执行
pip download。
wheel 文件名里的标签其实就是一个「兼容性断言」。可以把可复用的集合写成三个约束的交集:
只要三者中任意一个为空,就必须回退到 sdist 源码构建——这就是「装得上」与「要编译」的分界线。
十、依赖冲突的排查方法
10.1 第一招:pip check
python -m pip check
实测输出(存在真实冲突时):
requests 2.25.0 has requirement idna<3,>=2.5, but you have idna 3.20.
requests 2.25.0 has requirement urllib3<1.27,>=1.21.1, but you have urllib3 2.0.2.
无冲突时输出 No broken requirements found.。退出码非 0 表示有冲突,因此它很适合放进 CI 做门禁。
10.2 第二招:观察安装时的解析器警告
pip 在安装时会主动提示已存在的冲突(实测输出):
ERROR: pip's dependency resolver does not currently take into account all the packages
that are installed. This behaviour is the source of the following dependency conflicts.
requests 2.25.0 requires idna<3,>=2.5, but you have idna 3.20 which is incompatible.
读懂这句话
pip 的解析器只保证「本次请求」的依赖图自洽,它不会为了修好整个环境而回退你已经装的包。
一旦出现这段文字,说明环境已经不一致——不要忽略它,否则故障会延迟到运行时才爆发。
用集合语言可以把「冲突」精确定义出来。设包 需要依赖 ,其版本约束对应一个允许版本集合 ,当前环境里 的版本为 。则依赖一致当且仅当对所有包 与所有依赖 都成立:
也就是说,每个包的版本必须落在所有约束它的包的交集里。若某个 的交集为空集 ,该环境就无解——这正是 pip check 报出的那类错误。它解释了为什么冲突往往由第三个包的加入触发:新约束把交集压成了空集。
为什么「依赖解析」在理论上很难
依赖求解的一般形式是:给每个包选一个版本,使所有约束同时成立。这是约束满足问题(CSP),
其一般情形是 NP 难的,可选版本组合数随包数指数增长:
其中 为包数、 为平均可选版本数。因此所有工具(pip、uv、poetry)都依赖回溯加启发式剪枝,
而不是穷举——这也解释了为什么换用 Rust 实现的
uv能显著更快:同样的算法常数小得多。
10.3 第三招:查看依赖树
pip install pipdeptree
pipdeptree # 完整依赖树
pipdeptree -p requests # 只看某个包的子树
pipdeptree --warn silence # 降噪
# 使用 uv / poetry 时自带等价命令:
uv tree
poetry show --tree
也可以用标准库自己写一个最小版探查脚本——好处是不需要额外安装任何东西:
"""不依赖第三方库,打印某个包的依赖与反向依赖(依赖树的最小实现)。"""
from importlib.metadata import PackageNotFoundError, distribution, distributions, requires, version
def report(package_name: str) -> None:
try:
print(f"== {package_name} == {version(package_name)}")
except PackageNotFoundError:
print(f"{package_name} 未安装")
return
direct = requires(package_name) or []
print(" 依赖(它需要谁):")
for spec in direct:
print(" -", spec)
# 反向依赖:遍历所有已安装包的元数据,找出谁声明依赖了它
reverse = []
for dist in distributions():
try:
for spec in (dist.requires or []):
if spec.split()[0].split(";")[0].strip().lower() == package_name.lower():
reverse.append(dist.metadata["Name"])
break
except Exception:
continue # 个别包元数据损坏时不应中断整体排查
print(" 被依赖(谁需要它):", sorted(set(reverse)) or "(无)")
if __name__ == "__main__":
import sys
report(sys.argv[1] if len(sys.argv) > 1 else "requests")
10.4 排查流程(按顺序执行)
① where python / which -a python → 是不是有多个解释器?确认当前用的是哪个
② python -c "import sys;print(sys.prefix)" → 确认到底在不在虚拟环境里
③ python -m pip show <包名> → Location 字段确认包装到了哪个目录
④ python -m pip check → 是否有版本不满足的依赖关系
⑤ 看依赖树(pipdeptree / uv tree) → 谁把冲突的版本拉进来的
⑥ 修:调整约束 / 升级直接依赖 / 隔离环境重建
最常见的三种冲突根因及其解法
| 现象 | 根因 | 解法 |
|---|---|---|
|
ModuleNotFoundError但pip list里有 | 装到了另一个解释器 / 另一个环境 | 统一用python -m pip,核对Location|| 某包版本被莫名降级 | 另一个包的上限约束更严 | 看依赖树找到约束来源,升级那个包 |
| 多环境行为不一致 | 依赖漂移(没锁版本) | 引入锁文件,固定全部传递依赖 |
十一、项目目录结构最佳实践
my-project/
├── .venv/ # 虚拟环境(不进版本控制)
├── .gitignore
├── .python-version # 声明需要的 Python 版本(uv/pyenv 识别)
├── README.md # 项目说明:装什么、怎么跑
├── LICENSE
├── pyproject.toml # 唯一的配置中心(依赖 + 构建 + 工具配置)
├── uv.lock # 锁文件:应用要提交,库不要提交
├── src/ # ★ src 布局
│ └── my_tool/
│ ├── __init__.py
│ ├── cli.py
│ └── core.py
├── tests/ # 测试与源码分开放
│ ├── conftest.py
│ ├── test_core.py
│ └── fixtures/
├── docs/
├── scripts/ # 开发/运维脚本(不属于发布的包)
└── .github/workflows/ci.yml # CI 配置
11.1 为什么推荐 src 布局
# 平铺布局(不推荐) # src 布局(推荐)
my-project/ my-project/
├── my_tool/ ├── src/
│ └── __init__.py │ └── my_tool/
├── tests/ │ └── __init__.py
└── pyproject.toml └── tests/
| 方面 | 平铺布局 | src 布局 |
|---|---|---|
| 能否误测「源码目录」而非「已安装包」 | 会:当前目录在 sys.path 里,import my_tool 直接命中源码,打包配置错了也测不出来 | 不会:必须先安装/可编辑安装才能导入,暴露打包错误 |
| 测试时导入的是 | 可能是源码树 | 一定是安装后的包 |
| 对 IDE 与类型检查器 | 容易把测试文件也当作包 | 边界清晰 |
| 结论 | 适合一次性脚本 | 适合所有要发布或长期维护的项目 |
11.2 .gitignore 应该排除什么
# ---- Python 运行时产物 ----
__pycache__/
*.py[cod] # .pyc / .pyo / .pyd
*$py.class
# ---- 虚拟环境(绝不能提交,本地路径与平台都不同)----
.venv/
venv/
env/
ENV/
# ---- 构建与分发包产物 ----
build/
dist/
*.egg-info/
*.egg
.eggs/
wheels/
# ---- 测试与覆盖率 ----
.pytest_cache/
.coverage
.coverage.*
htmlcov/
.tox/
.nox/
# ---- 类型检查与工具缓存 ----
.mypy_cache/
.ruff_cache/
.hypothesis/
# ---- 打包前用于验证的本地安装目录 ----
.Python
# ---- IDE / 编辑器 ----
.idea/
.vscode/ # 若团队共享配置,则改为 .vscode/settings.json 显式提交
*.swp
两个常见误操作
1. 把
.venv提交了:仓库体积暴涨、跨平台无法使用、还会让git status永远有噪声。一旦提交过,即使后来加了
.gitignore也仍然被跟踪,需要git rm -r --cached .venv。2. 把锁文件忽略了:
uv.lock/poetry.lock是应用项目必须提交的文件,忽略它就等于放弃了可复现构建。但库项目不该提交锁文件,因为它会把你的开发环境版本强加给下游。
十二、打包发布自己的库
# ① 安装构建与上传工具
pip install --upgrade build twine
# ② 清理历史产物(否则可能误上传旧版本)
rm -rf dist/ build/ src/*.egg-info/
# ③ 构建:生成 sdist(源码包)与 wheel(二进制分发包)
python -m build
# dist/
# ├── my_tool-0.1.0-py3-none-any.whl ← 纯 Python 包的 wheel
# └── my_tool-0.1.0.tar.gz ← sdist
# ④ 本地校验元数据(能在上传前发现大部分格式问题)
twine check dist/*
# ⑤ 先传到测试仓库演练,确认无误再传正式仓库
twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ my-tool
# ⑥ 正式上传(凭证用 API token,不要用账号密码)
twine upload dist/*
| 概念 | 说明 | 常见坑 |
|---|---|---|
| sdist | 源码分发包 .tar.gz,安装时可能需要在目标机编译 | 漏写 MANIFEST.in 会丢文件 |
| wheel | 预构建分发包 .whl,安装无需编译 | 纯 Python 包名形如 py3-none-any;带 C 扩展要按平台构建 |
| 版本号 | 一旦上传不可覆盖、不可删除(可 yank) | 必须在 pyproject.toml 里手工升版本 |
| 元数据校验 | twine check 检查 README 渲染与字段 | 跳过它常导致 PyPI 页面显示异常 |
发布前必查清单
1.
requires-python是否与实际支持范围一致;2.
README.md里的用法示例能否从安装开始跑通(很多库的示例默认已经import成功);3. 版本号是否更新(忘了升版本会直接被 PyPI 拒绝);
4. 依赖范围是否过窄(写成
==会让下游无法共存);5. 是否已在 TestPyPI 演练过一遍。
永远不会删除已发布的版本
PyPI 不允许删除已发布的版本号,只能「Yank」(隐藏但不删)。因此任何一次上传都应视为永久行为,
上传前务必在 TestPyPI 演练。凭证请使用作用域受限的 API token,而不是账号密码。
十三、注意事项与常见坑
坑 1:把虚拟环境目录提交到 Git
见 11.2 节。修复命令:
git rm -r --cached .venv之后再提交。
坑 2:在错误的环境里装包(最高频)
症状是「明明装了,却
ModuleNotFoundError」。永远用python -m pip install,并用
python -m pip show <包> | findstr Location(Linux 用grep Location)确认落点。
坑 3:PowerShell 里
pip install requests>=2.28报错PowerShell 把
>解释为重定向符号,会生成一个名为=2.28的文件。所有含版本约束的需求必须加引号:
pip install "requests>=2.28"。
坑 4:移动或重命名了虚拟环境目录
pyvenv.cfg与激活脚本里记录的是绝对路径,移动后环境即失效。虚拟环境是不可移植的:换机器、换目录一律重建,不要拷贝。
坑 5:
pip freeze里出现-e file:///D:/...那是可编辑安装的本地包,写进
requirements.txt后别人无法安装。应把它移到
requirements-dev.txt,或在发布用文件里手工删除该行。
坑 6:只固定直接依赖就以为可复现
requests==2.31.0并不会固定urllib3的版本,而urllib3的行为差异同样能搞崩你。需要可复现就用锁文件(
uv.lock/poetry.lock)或pip-compile生成全量固定文件。
坑 7:在虚拟环境里用全局的
pip升级自己
python -m pip install --upgrade pip在环境内执行才是升级该环境的 pip。若用错解释器,可能把系统 pip 升成与系统包不兼容的版本。
坑 8:不写
requires-python就发布下游在 3.8 上安装你的包,装成功但 import 就崩——因为你在代码里用了
list[int]。
requires-python = ">=3.9"能让 pip 在安装阶段就拒绝,而不是留到运行时。
坑 9:src 布局下漏写
__init__.pyPython 3.3 起支持隐式命名空间包(PEP 420),没有
__init__.py的目录照样能被import。后果是:本地开发时
import my_tool正常,构建出的 wheel 里却没有这个包,只有装到别的环境才暴露
ModuleNotFoundError。这正是 src 布局的价值所在——它把这类问题提前到
pip install -e .阶段。稳妥做法是显式保留
src/my_tool/__init__.py(哪怕是空文件),并在pyproject.toml里确认构建后端的包发现配置,装完后运行
twine check dist/*与一次真实安装验证。
坑 10:把
.venv一起打进 Docker 镜像复制
COPY . .而不写.dockerignore,会把本地的 Windows 虚拟环境搬进 Linux 镜像:镜像体积暴涨几百 MB,且里面的可执行文件在容器里根本不能用。
.dockerignore必须与.gitignore同步维护,至少包含.venv/、__pycache__/、.git/。
十四、练习题
- 基础题:创建项目
hello-pkg,用python -m venv .venv建环境,安装requests,然后
用 python -m pip show requests 找出它的安装路径,并解释为什么这个路径在虚拟环境里。
- 基础题:写出一个
requirements.txt,要求:flask用 3.x 系列、requests不低于 2.28 但不跨大版本、
pytest 仅在开发时安装、pywin32 仅在 Windows 上安装。再用 pip install --dry-run -r 验证它能解析成功。
- 进阶题:在干净的虚拟环境里故意制造一次依赖冲突(提示:先装
requests==2.25.0,再用--no-deps强装
idna==3.20),然后用 pip check 复现报错,并写出修复它的两种不同思路及其代价。
- 进阶题:把一个已有的平铺布局项目改造成 src 布局,要求
python -m build产出的 wheel 中确实包含全部模块,
并说明改造后为什么「打包漏文件」这类错误会更容易在测试阶段暴露。
- 思考题:团队里有 3 个项目,其中 2 个是要发布到 PyPI 的库,1 个是内部服务。
请分别说明它们该不该提交锁文件、dependencies 里的版本约束该写宽还是写窄,以及理由。
十五、常见问题(FAQ)
Q1:虚拟环境里的 python.exe 是复制出来的吗?需要和原解释器版本一致吗?
A:不是完整复制。Windows 上 venv 默认放置的是解释器的副本或符号链接,标准库仍从 pyvenv.cfg 里的 home 指向的真实安装目录加载。因此虚拟环境的版本永远等于创建它的那个解释器版本,想换 Python 版本必须用新解释器重新创建环境(uv python install 3.13 && uv venv --python 3.13)。
Q2:venv 和 conda 该用哪个?
A:两者定位不同。venv 只管 Python 包,轻量、标准库自带;conda 还管理非 Python 依赖(如 CUDA、MKL、编译好的 numpy),适合科学计算与需要二进制依赖隔离的场景。纯 Python 项目用 venv 即可;一旦涉及 GPU/C 库版本冲突,conda(或 mamba)更省事。两者不要嵌套混用。
Q3:requirements.txt 和 pyproject.toml 都要写吗?
A:分工不同。pyproject.toml 是项目元数据(发布时给下游看的宽范围依赖),requirements.txt / 锁文件是具体环境快照(部署时用的精确版本)。库项目以 pyproject.toml 为准,requirements-dev.txt 只服务开发环境;应用项目可以用工具从 pyproject.toml 生成锁文件,避免两处维护。
Q4:为什么 pip install 有时会尝试从源码编译,还失败?
A:当你需要的版本在目标平台上没有预编译 wheel 时,pip 会下载 sdist 并在本地构建,这就需要编译器(Windows 上通常缺 MSVC Build Tools)。可行的对策按优先级:① 换用有 wheel 的版本;② 加 --only-binary=:all: 让其尽早报错而不是编译到一半失败;③ 装对应平台的预编译包或使用 conda;④ 最后才考虑安装编译器。
相关笔记
- Python-01-环境与基础语法:解释器安装与运行方式,虚拟环境是它的直接延伸
- Python-02-内置数据结构:包的导入路径与模块加载顺序,决定了
site-packages与项目包的优先级 - Python-04-面向对象:把项目组织成可发布的包时,类的设计与
__init__.py的导出约定都会用到 - Python-05-异常与文件IO:路径处理(
pathlib)与异常排查,是诊断「装到哪儿去了」的基本功
参考来源
- Python 官方文档 ·
venv创建虚拟环境:https://docs.python.org/zh-cn/3/library/venv.html - Python 官方文档 · 安装 Python 模块:https://docs.python.org/zh-cn/3/installing/index.html
- pip 官方文档 · 命令行参考:https://pip.pypa.io/en/stable/cli/
- pip 官方文档 ·
pip freeze:https://pip.pypa.io/en/stable/cli/pip_freeze/ - pip 官方文档 ·
pip check:https://pip.pypa.io/en/stable/cli/pip_check/ - pip 官方文档 · 配置文件与
pip config:https://pip.pypa.io/en/stable/topics/configuration/ - PEP 405 · Python Virtual Environments:https://peps.python.org/pep-0405/
- PEP 518 · Specifying Minimum Build System Requirements:https://peps.python.org/pep-0518/
- PEP 621 · Storing project metadata in pyproject.toml:https://peps.python.org/pep-0621/
- Python Packaging User Guide · 打包项目教程:https://packaging.python.org/en/latest/tutorials/packaging-projects/
- Python Packaging User Guide · src 布局与项目结构:https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/
- uv 官方文档:https://docs.astral.sh/uv/
- Poetry 官方文档:https://python-poetry.org/docs/
- PDM 官方文档:https://pdm-project.org/latest/
- Real Python · Python Virtual Environments 入门:https://realpython.com/python-virtual-environments-a-primer/
版本敏感性说明
本文涉及工具版本与特性的内容——
uv/poetry/pdm的命令与能力、pyproject.toml中license等字段的新写法、pip 的报错文案与选项、镜像源地址——均可能随版本变化,以官方最新文档为准。文中的 pip/venv 实测输出基于 CPython 3.12 与 pip 25.x,性能与耗时数字来自单机测量,仅用于说明趋势。