5分钟Python · 包管理 | 一个命令，把混乱的依赖关系理得清清楚楚
pipdeptree 是一个非常有用的命令行工具，它能以树形结构清晰地展示当前 Python 环境中所有已安装包的依赖关系，让我们对项目依赖一目了然。
1. 安装
使用 pip install 命令安装：
pip install pipdeptree
如果需要用到 from-index 等与包索引交互的高级功能，可以安装额外的依赖项：
pip install pipdeptree[index]
支持的可选 extra 包括 graphviz、index、rich 等，用于不同功能的扩展。
2. 基础用法
在命令行中直接输入 pipdeptree，它会列出当前环境下所有包及其依赖树：
pipdeptree
输出示例：
从输出中可以看出，accelerate 依赖 huggingface-hub，而 huggingface-hub 又依赖 filelock。
3. 常用选项
-p, --packages：筛选特定包
只查看特定包的依赖关系。比如，想看 akshare 包依赖了哪些包：
pipdeptree -p akshare
输出：
-r, --reverse：反向查找
如果想知道一个包被谁使用，即谁依赖它，可以使用反向查找。这个功能在排查冗余依赖时尤其好用。
pipdeptree --reverse --packages numpy
输出：以上命令将列出所有依赖 numpy 的包。
-w, --warn：控制冲突警告
pipdeptree 默认会检测并报告环境中存在的依赖冲突（如A包需要some-package版本1.0，而B包需要版本2.0）和循环依赖。警告信息会打印到 stderr。
可以通过 --warn 控制其行为：
--warn silence：完全静默，不显示任何警告，总是以状态码0退出。--warn suppress (默认)：显示警告，但仍以状态码0退出。--warn fail：显示警告，并在存在任何冲突或循环依赖时以非0状态码退出。这个选项特别适合用在 CI/CD 流水线中，如果依赖关系不健康，可以让构建失败。
# 在 CI 中，如果发现冲突则让脚本失败pipdeptree --warn fail
--python：指定虚拟环境
如果在全局环境安装了 pipdeptree，但想检查某个特定的虚拟环境，可以使用 --python 选项：
pipdeptree --python /path/to/your/venv/bin/python
示例：
pipdeptree --python .\my-code\deepseek-multi-model\.venv\Scripts\python.exe
输出：
从 2.21.0 版本开始，还可以使用 --python auto 让工具尝试自动检测当前激活的虚拟环境。
pipdeptree --python auto
输出：
deepseek-multi-model==0.1.0└── requests [required: >=2.31.0, installed: 2.32.5] ├── certifi [required: >=2017.4.17, installed: 2025.11.12] ├── charset-normalizer [required: >=2,<4, installed: 3.4.4] ├── idna [required: >=2.5,<4, installed: 3.11] └── urllib3 [required: >=1.21.1,<3, installed: 2.6.2]openai==2.14.0├── anyio [required: >=3.5.0,<5, installed: 4.12.0]│ └── idna [required: >=2.8, installed: 3.11]├── distro [required: >=1.7.0,<2, installed: 1.9.0]......
4. 输出与集成
pipdeptree 支持多种输出格式，方便与其他工具集成。
-f, --freeze：生成 requirements.txt
这是 pipdeptree 在实际项目中非常关键的用法。它可以生成包含所有直接和间接依赖的、可直接用于 pip install -r 的 "锁文件"。
pipdeptree -f | tee requirements-lock.txt
输出的文件内容类似于：
(resolved python: D:\my-code\deepseek-multi-model\.venv\Scripts\python.exe)Warning!!! Duplicate package metadata found:"D:\my-code\deepseek-multi-model\.venv\Lib\site-packages" deepseek-multi-model 0.1.0 (using 0.1.0, ".")NOTE: This warning isn't a failure warning.------------------------------------------------------------------------deepseek-multi-model==0.1.0 requests==2.32.5 certifi==2025.11.12 charset-normalizer==3.4.4 idna==3.11 urllib3==2.6.2openai==2.14.0 anyio==4.12.0 idna==3.11 distro==1.9.0 httpx==0.28.1 anyio==4.12.0 idna==3.11 certifi==2025.11.12 httpcore==1.0.9 certifi==2025.11.12 h11==0.16.0 idna==3.11 jiter==0.12.0 pydantic==2.12.5 annotated-types==0.7.0 pydantic_core==2.41.5 typing_extensions==4.15.0 typing_extensions==4.15.0 typing-inspection==0.4.2 typing_extensions==4.15.0 sniffio==1.3.1 tqdm==4.67.1 colorama==0.4.6 typing_extensions==4.15.0
-f 标志会移除子依赖项前的 - 符号，使得文件符合 pip freeze 的格式要求。
-o, --output：结构化数据输出
支持输出为 json、mermaid 或 graphviz-svg 等格式，便于可视化或机器处理。
pipdeptree -o json
JSON 格式输出示例：
pipdeptree -o mermaid
Mermaid 格式示例：
PS D:\my-code\deepseek-multi-model> pipdeptree -o mermaid(resolved python: D:\my-code\deepseek-multi-model\.venv\Scripts\python.exe)flowchart TD classDef missing stroke-dasharray: 5 annotated-types["annotated-types<br/>0.7.0"] anyio["anyio<br/>4.12.0"] certifi["certifi<br/>2025.11.12"] charset-normalizer["charset-normalizer<br/>3.4.4"] colorama["colorama<br/>0.4.6"] deepseek-multi-model["deepseek-multi-model<br/>0.1.0"] distro["distro<br/>1.9.0"]......
--summary：生成环境健康报告
可以生成一个摘要报告，包含包的总数、依赖深度、冲突和循环依赖数量、许可证等信息，有助于快速评估环境健康度。
pipdeptree --summary
PS D:\> pipdeptree --summarytotal packages: 445direct dependencies: 73transitive dependencies: 372max depth: 9cyclic dependencies: 0missing dependencies: 0conflicting dependencies: 0(0 edges)licenses: (Apache Software License): 66, (Apache Software License, GNU General Public License v2 (GPLv2)): 1, (Apache-2.0 OR BSD-2-Clause): 1, (Apache-2.0): 26, (BSD License): 82, (BSD License, Apache Software License): 1, (BSD License, Apache Software License, Public Domain): 1, (BSD License, Other/Proprietary License): 1, (BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0): 1, (BSD-3-Clause AND TCL): 1, (BSD-3-Clause): 5, (GNU General Public License v2 (GPLv2)): 1, (GNU Lesser General Public License v2 or later (LGPLv2+)): 1, (GNU Lesser General Public License v3 (LGPLv3)): 1, (GNU Lesser General Public License v3 or later (LGPLv3+)): 1, (GNU Library or Lesser General Public License (LGPL)): 2, (GPL-2.0-or-later): 1, (GPL-3.0-or-later): 1, (Historical Permission Notice and Disclaimer (HPND)): 1, (ISC License (ISCL)): 2, (ISC): 2, (LGPL-2.1-or-later): 1, (LGPL-3.0-only): 1, (MIT AND PSF-2.0): 1, (MIT License): 114, (MIT License, Apache Software License): 2, (MIT License, Mozilla Public License 2.0(MPL 2.0)): 1, (MIT): 53, (MPL-2.0 AND (Apache-2.0 OR MIT)): 1, (Mozilla Public License 2.0(MPL 2.0)): 3, (N/A): 54, (OSI Approved): 2, (PSF-2.0): 1, (Public Domain, Python Software Foundation License, BSD License, GNU General Public License (GPL)): 1, (Python Software Foundation License): 8, (The Unlicense (Unlicense)): 2, (zlib/libpng License): 1unknown licenses: 54copyleft licenses: yesmin requires-python: 3.13total size: 3.9 GB
pipdeptree --summary -o rich
富文本输出示例:
可视化依赖图
如果想更直观地查看依赖关系，可以安装 graphviz 包并使用 --graph-output 生成图表。
pip install pipdeptree[graphviz]
pipdeptree --graph-output svg > dependencies.svg
输出部分截图：
5. 高级功能
from-index：不安装即可预览依赖树
从较新的版本开始，pipdeptree 可以不实际安装包，仅通过解析包索引来生成依赖树，这在评估新包时很实用。
pipdeptree from-index "flask"
输出示例：
PS D:\> pipdeptree from-index "flask"flask==3.1.3├── blinker [candidate: 1.9.0]├── click [candidate: 8.4.2]│ └── colorama [candidate: 0.4.6]├── itsdangerous [candidate: 2.2.0]├── jinja2 [candidate: 3.1.6]│ └── markupsafe [candidate: 3.0.3]├── markupsafe [candidate: 3.0.3]└── werkzeug [candidate: 3.1.8] └── markupsafe [candidate: 3.0.3]
6. 注意事项
- 依赖内部 API：
pipdeptree 依赖于 pip 的内部 API 来获取已安装包的信息。当 pip 发布大版本更新时，pipdeptree 可能会暂时失效，直到其作者修复适配。在自动化流水线中固定 pip 的版本可以规避此风险。 - 离线环境：在离线环境中，
pipdeptree 的 from-index 功能无法使用，因为它需要访问 PyPI。但仍可正常使用其核心的依赖树查看功能。
7. 总结
依赖关系清晰化：pipdeptree 可以清晰地显示依赖关系，使得项目依赖一目了然，方便调试和维护。
依赖分析：pipdeptree 可以帮助你分析依赖关系，了解哪些包是直接依赖，哪些是间接依赖，如何管理依赖等。
环境健康度评估：pipdeptree 可以帮助你评估依赖环境的健康度，了解哪些包的版本冲突可能会导致问题，如何解决冲突等。
过去我们使用 pip freeze 和 requirements.txt 来管理依赖。如今，像 uv 这类新一代工具已经能通过原生锁文件（uv.lock）保证完全可复现的环境，安装速度也比 pip 快 8 倍以上。但无论工具如何进化，pipdeptree 作为诊断工具的价值从未过时——**它是 Python 依赖环境的"CT 扫描仪"**，排查问题时总能派上用场。
