Python 依赖管理：Pipfile 与 Pipfile.lock

最新推荐文章于 2025-11-24 15:28:47 发布

原创最新推荐文章于 2025-11-24 15:28:47 发布 · 353 阅读

18 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言

python 专栏收录该内容

44 篇文章

订阅专栏

本文档详细介绍了 Python 项目中 Pipfile 和 Pipfile.lock 的作用、原理，以及它们与传统 requirements.txt 的区别。

1. 它们是什么？

这两个文件是 Python 依赖管理工具 Pipenv 的核心组件。

如果你熟悉前端开发（Node.js），可以这样类比：

Pipfile $\approx$ package.json
Pipfile.lock $\approx$ package-lock.json 或 yarn.lock

它们的设计目的是为了解决 Python 传统依赖管理（pip + requirements.txt）中的一些痛点，如版本冲突、开发依赖分离困难、环境一致性差等。

2. 文件详解

2.1 Pipfile (给人看的)

这是一个 TOML 格式的文件，用来声明项目需要哪些包。它只记录你直接安装的顶层依赖。

主要特点：

易读性：结构清晰。
环境分离：明确区分 [packages]（生产环境）和 [dev-packages]（开发测试环境）。
版本灵活：通常只指定最低版本或模糊版本（如 *），表明意图。
Python 版本指定：可以锁定项目所需的 Python 解释器版本。

示例 Pipfile:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"          # 安装最新版
fastapi = ">=0.68.0"    # 指定最低版本

[dev-packages]
pytest = "*"
black = "*"

[requires]
python_version = "3.10"

2.2 Pipfile.lock (给机器看的)

这是一个自动生成的 JSON 文件，绝对不应该手动修改。

主要特点：

确定性构建 (Deterministic Builds)：它通过运行 pipenv lock 生成，将 Pipfile 中模糊的依赖解析为具体的版本号（例如 requests 的 * 变成了 2.28.1）。
依赖树锁定：不仅仅锁定你安装的包，还锁定了这些包所依赖的所有子包（Sub-dependencies）。
安全哈希：包含每个包文件的 Hash 值。这保证了在任何机器上安装时，下载的文件内容必须与生成 Lock 文件时完全一致，防止中间人攻击或包被篡改。

3. 为什么很多人“写了很久 Python 也没用过”？

这在 Python 社区非常正常，主要原因有三点：

requirements.txt 的统治地位
- 它是 Python 最原始、最通用的依赖列举方式。
- 几乎所有的云平台（AWS, GCP, Azure）、CI/CD 工具和 IDE 都原生完美支持它。
- 对于简单的脚本或小型微服务，它完全够用。
生态分裂 (The “Packaging War”)
- Python 的包管理工具有很多流派。
- Conda: 数据科学和 AI 领域（PyTorch, TensorFlow）通常使用 Conda 和 environment.yml，完全不依赖 Pipenv。
- Poetry / PDM / uv: 这是目前更现代的选择。Pipenv 曾有一段时间维护停滞，导致社区转向了基于官方标准 pyproject.toml 的工具（如 Poetry）。
非官方标准
- Pipfile 是 Pipenv 项目定义的格式，并不是 Python 官方标准（PEP）。目前的官方趋势是统一使用 pyproject.toml 来管理项目配置和依赖。

4. 对比：Pipenv vs requirements.txt

特性	requirements.txt	Pipfile / Pipenv
依赖解析	弱（容易出现版本冲突）	强（自动计算版本兼容性）
版本锁定	需要手动 `pip freeze` (不直观)	自动 (`Pipfile.lock` 锁定所有子依赖)
开发依赖	通常需要维护两个文件 (`requirements.txt`, `dev.txt`)	内置支持 (`[dev-packages]`)
虚拟环境管理	手动 (`python -m venv venv`)	自动 (自动创建和管理 hidden venv)
安装速度	快	慢 (依赖解析算法复杂，Lock 过程较慢)
通用性	极高	中等 (需要安装 pipenv)

5. 什么时候该用哪个？

继续使用 requirements.txt：
- 你正在编写 Docker 镜像（如本项目），pip install -r requirements.txt 是最简单、层级最少的命令。
- 团队已经习惯了这种方式，且项目依赖关系不复杂。
使用 Pipenv (Pipfile)：
- 你需要严格的确定性构建，确保生产环境和开发环境的每一个包版本（包括子依赖）都连 Hash 值都一样。
- 你喜欢不用手动管理 source venv/bin/activate 的便利。
使用 Poetry / uv (pyproject.toml)：
- 推荐方向。如果你要开始一个新项目，或者想要构建一个 Python 包发布到 PyPI。
- 它们使用现代标准的 pyproject.toml，速度更快（尤其是 uv），体验更好。