Python依赖入门：pip与PyPI的基本使用、requirements.txt编写

说实话，Python 生态里最让我省心的就是 pip 和 PyPI 这套机制。你不需要像 C++ 那样到处找 .h 文件和 .lib，也不用像 Java 那样折腾 Maven 的 settings.xml。一行命令，依赖到手。但如果你用不好，也容易踩坑——我见过太多人因为 requirements.txt 写得稀烂，导致项目在别人机器上跑不起来。

3.1 pip：Python 的包管理器

pip 是 Python 官方推荐的包管理工具。从 Python 3.4 开始，它已经内置在安装包中了。你可以在终端里验证：

pip --version

我个人习惯先检查一下版本，如果低于 21.0，我建议升级：

python -m pip install --upgrade pip

嗯，这里要注意——用 python -m pip 而不是直接 pip，可以避免路径混乱。我在项目中遇到过因为系统 pip 和虚拟环境 pip 搞混，装了包却找不到的情况。

基本操作 其实就四个：

  • pip install <包名> —— 安装包
  • pip uninstall <包名> —— 卸载
  • pip list —— 列出已安装的包
  • pip show <包名> —— 查看包详情

举个实际的例子，假设你要用 requests 库：

pip install requests

pip 会自动去 PyPI 找最新稳定版，下载并安装，顺带解决依赖。我曾经犯过一个错：直接在系统 Python 里装包，后来项目多了，依赖全混在一起。所以我现在强烈建议你——在虚拟环境里操作。后续章节会讲到虚拟环境，但请记住这个原则。

3.2 PyPI：Python 包索引

PyPI 全称 Python Package Index，是官方仓库。所有的开源 Python 包都发布在上面。你可以在 pypi.org 搜索，也可以直接用 pip 搜索（虽然不怎么好用）。

有个常见问题：国内访问 PyPI 很慢。怎么办？换镜像源。我习惯用清华源：

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

或者永久配置：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

注意： 不建议在公共 CI 里用镜像源，除非你确定它稳定。我以前遇到过镜像源同步延迟，导致生产环境装了个旧版本，排查了半天。后来我改成在 CI 里先切换到官方源，再指定 --trusted-host。

PyPI 上每个包都有一个主页，包含文档、源码链接、版本历史。发布自己的包其实不难，但今天我们只聚焦“消费者”视角——怎么用好它。

3.3 requirements.txt：依赖清单的艺术

好，现在你装了一大堆包。但怎么告诉队友“我用了哪些包”？嗯，用 requirements.txt。

最简单的生成方式：

pip freeze > requirements.txt

然后别人拿到你的代码，只要执行：

pip install -r requirements.txt

就能还原一模一样的依赖环境。听起来很完美？但这里有个大坑——

我曾经 在项目初期用 pip freeze > requirements.txt 直接生成，结果文件里出现了几十个间接依赖（比如 requests 依赖 urllib3，urllib3 又依赖 certifi）。版本都没固定，导致半年后重新部署时，urllib3 自动升级了，requests 行为变了。那一次我花了整整两天定位。

所以现在我写 requirements.txt 会遵循几条原则：

  1. 只记录顶层依赖，除非某个间接依赖有特殊版本要求。
  2. 锁定主版本号，允许小版本更新（比如 requests>=2.28,<3）。
  3. 生产环境必须精确锁定（用 ==2.28.1），开发环境可以放宽。

下面是个典型的 requirements.txt 例子：

requests>=2.28,<3
flask>=2.3,<3
numpy==1.24.3
pandas>=1.5,<2

版本约束符号有以下几种，我整理了个表格：

符号 含义 示例
==精确版本requests==2.28.1
>=大于等于requests>=2.28
<=小于等于requests<=3.0
> / <严格大于/小于requests>2.27
~=兼容版本（等价于 >=X.Y, ==X.*）requests~=2.28 允许 2.28.x
!=排除特定版本requests!=2.28.0
*任意版本（不推荐）requests==*

我的小技巧： 用 pip-compile（来自 pip-tools 包）自动生成锁定版本的 requirements.txt。它会帮你解析依赖树，只保留你需要的顶层包，并自动锁定所有间接依赖。在团队里，我会在仓库里同时维护两份：requirements.in（写顶层依赖和范围）和 requirements.txt（锁定的精确版本，提交到版本控制）。

还有个小细节：requirements.txt 可以指定可选依赖组，比如 .[dev]。但新手阶段先掌握基础的就好。

pip与requirements.txt协作流程 本地开发环境 pip install PyPI 仓库 包索引 本地缓存 pip cache 安装到环境 site-packages pip freeze 生成清单 requirements.txt 版本锁定 团队拉取 pip install -r 版本锁定原则： 顶层包写范围，间接包精确锁定

本节核心要点：

  • pip 是 Python 生态的基石，务必与虚拟环境配合使用。
  • PyPI 是依赖来源，国内用户配置镜像源能大幅提升速度。
  • requirements.txt 不是简单的 pip freeze 输出，而是团队协作的契约。我建议你在项目初期就定好版本策略，否则后面改起来非常痛苦。

最后再说一句：别把 pip freeze 输出直接扔进 git 就完事了。我用过一段时间 pipenv 和 poetry，但最终觉得原生的 requirements.txt 搭配 pip-tools 最轻量可控。工具不在多，顺手就好。

← 上一章 📖 返回目录 下一章 →