如何一键理清大型Python项目依赖树

方予

发布时间：2026-10-15| 6人浏览过

原创

本文介绍如何使用pipdeptree工具可视化Python项目的依赖树。通过对比pip freeze，展示其检测版本冲突和循环依赖的能力，并演示如何生成锁定文件和基于GraphViz的可视化图表，帮助开发者高效清理大型项目的依赖关系。

前言：

在开发过程中，经常因包版本不匹配引发代码报错。由于pip freeze仅以二维列表形式展示所有依赖项，定位具体错误版本的包往往十分繁琐。此时，推荐一款必备工具：pipdeptree。

pipdeptree是一款命令行实用程序，旨在以依赖关系树的形式可视化展示已安装的Python包。

该工具既适用于全局安装在计算机上的模块，也适用于Virtualenv等虚拟环境中的模块。

1.安装

只需在目标环境中执行以下命令即可完成pipdeptree的安装：

pip install pipdeptree

已通过测试的Python版本包括：2.7，3.5，3.6，3.7，3.8，3.9。

2.用法和示例

pip freeze与pipdeptree的主要区别如下：

# pip freeze 的显示
$ pip freeze
Flask==0.10.1
itsdangerous==0.24
Jinja2==2.11.2
-e git+git@github.com:naiquevin/lookupy.git@cdbe30c160e1c29802df75e145ea4ad903c05386#egg=Lookupy
MarkupSafe==0.22
pipdeptree @ file:///private/tmp/pipdeptree-2.0.0b1-py3-none-any.whl
Werkzeug==0.11.2

可以看出，pip freeze最多只能显示一个依赖列表，而在pipdeptree中，每个模块的依赖关系得以直观呈现：

$ pipdeptree
Warning!!! Possibly conflicting dependencies found:
* Jinja2==2.11.2
 - MarkupSafe [required: >=0.23, installed: 0.22]
------------------------------------------------------------------------
Flask==0.10.1
  - itsdangerous [required: >=0.21, installed: 0.24]
  - Jinja2 [required: >=2.4, installed: 2.11.2]
    - MarkupSafe [required: >=0.23, installed: 0.22]
  - Werkzeug [required: >=0.7, installed: 0.11.2]
Lookupy==0.1
pipdeptree==2.0.0b1
  - pip [required: >=6.0.0, installed: 20.1.1]
setuptools==47.1.1
wheel==0.34.2

请注意其中的Warning提示，它指出了可能导致依赖模块版本冲突的模块。这一提示极具价值，许多问题往往就源于此。

此外，如果存在循环依赖，例如：

CircularDependencyA => CircularDependencyB => CircularDependencyA

系统将给出如下提示：

$ pipdeptree --exclude pip,pipdeptree,setuptools,wheel
Warning!!! Cyclic dependencies found:
- CircularDependencyA => CircularDependencyB => CircularDependencyA
- CircularDependencyB => CircularDependencyA => CircularDependencyB
------------------------------------------------------------------------
wsgiref==0.1.2
argparse==1.2.1

若需生成requirements.txt文件，可采取以下操作：

$ pipdeptree -f | tee locked-requirements.txt
Flask==0.10.1
  itsdangerous==0.24
  Jinja2==2.11.2
    MarkupSafe==0.23
  Werkzeug==0.11.2
gnureadline==8.0.0
-e git+git@github.com:naiquevin/lookupy.git@cdbe30c160e1c29802df75e145ea4ad903c05386#egg=Lookupy
pipdeptree @ file:///private/tmp/pipdeptree-2.0.0b1-py3-none-any.whl
  pip==20.1.1
setuptools==47.1.1
wheel==0.34.2

在确认无冲突依赖项后，甚至可以进行“锁定”，使所有包固定于当前安装的版本：

$ pipdeptree -f | sed 's/ //g' | sort -u > locked-requirements.txt

3. 可视化依赖树

为实现依赖树的可视化展示，需先安装GraphViz。安装完成后，输入以下命令：

pipdeptree --graph-output png > dependencies.png

# pipdeptree --graph-output dot > dependencies.dot
# pipdeptree --graph-output pdf > dependencies.pdf
# pipdeptree --graph-output svg > dependencies.svg

该工具支持四种格式的输出，此处以png格式为例，效果如下：