w wyl123ly 的博客
MD

Python-08-虚拟环境与包管理

43 KB 2026.10.11 原文件

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激活命令
WindowsPowerShell.venv\Scripts\Activate.ps1
Windowscmd.exe.venv\Scripts\activate.bat
WindowsGit Bashsource .venv/Scripts/activate
macOS / Linuxbash / zshsource .venv/bin/activate
macOS / Linuxfishsource .venv/bin/activate.fish
macOS / Linuxcsh / tcshsource .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

维度uvpoetrypdm
开发方Astral(Ruff 团队)Poetry 社区PDM 社区
实现语言RustPythonPython
定位极速的一体化替代(pip/venv/pipx/锁)面向「应用与库」的完整项目管理遵循 PEP 标准的现代项目管理
配置文件标准 pyproject.toml(PEP 621)自有 [tool.poetry] 表(新版也支持 PEP 621)标准 pyproject.toml(PEP 621)
锁文件uv.lockpoetry.lockpdm.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
清华大学 TUNAhttps://pypi.tuna.tsinghua.edu.cn/simple
阿里云https://mirrors.aliyun.com/pypi/simple/
腾讯云https://mirrors.cloud.tencent.com/pypi/simple/
中科大 USTChttps://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__.py

Python 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/。


十四、练习题

  1. 基础题:创建项目 hello-pkg,用 python -m venv .venv 建环境,安装 requests,然后

用 python -m pip show requests 找出它的安装路径,并解释为什么这个路径在虚拟环境里。

  1. 基础题:写出一个 requirements.txt,要求:flask 用 3.x 系列、requests 不低于 2.28 但不跨大版本、

pytest 仅在开发时安装、pywin32 仅在 Windows 上安装。再用 pip install --dry-run -r 验证它能解析成功。

  1. 进阶题:在干净的虚拟环境里故意制造一次依赖冲突(提示:先装 requests==2.25.0,再用 --no-deps 强装

idna==3.20),然后用 pip check 复现报错,并写出修复它的两种不同思路及其代价。

  1. 进阶题:把一个已有的平铺布局项目改造成 src 布局,要求 python -m build 产出的 wheel 中确实包含全部模块,

并说明改造后为什么「打包漏文件」这类错误会更容易在测试阶段暴露。

  1. 思考题:团队里有 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,性能与耗时数字来自单机测量,仅用于说明趋势。