一、基础知识

先认识几个名词:pip 是 Python 的包安装工具;PyPI 是官方的软件包仓库;源(index) 就是 pip 去哪里找包,默认是 PyPI,也可以换成国内镜像或公司私服;requirements.txt 是记录项目依赖及版本的文本文件。

版本号常见写法:精确锁定 ==,最低版本 >=,上限 <,兼容版本 ~=。例如:

requests==2.31.0
flask>=2.0,<3.0
numpy~=1.24.0

最关键的观念:依赖必须锁定到精确版本。只写 flask 不写版本,今天装和新一个月装可能得到不同版本,行为变了还找不到原因。锁定用 ==,并配合虚拟环境,是每个项目都应养成的习惯。

虚拟环境把不同项目的依赖隔开,避免 A 项目升级了包把 B 项目弄坏:

python -m venv .venv
source .venv/bin/activate          # macOS / Linux
.venvScriptsactivate             # Windows
python -m pip --version            # 确认用的是虚拟环境里的 pip

二、实操步骤

下面按五步,把一个项目的依赖管理做完整。

第 1 步:临时换源安装包

用 -i 参数指定仓库地址。官方 PyPI 的地址是 https://pypi.org/simple,国内镜像或公司私服的地址请查对应官方说明:

python -m pip install requests -i https://pypi.org/simple

临时换源只影响这一次命令,不改变全局配置,适合偶尔使用。

第 2 步:永久配置默认源

不想每次都写 -i,可以用 pip config 写入配置:

python -m pip config set global.index-url https://pypi.org/simple
python -m pip config list               # 查看当前配置
python -m pip config unset global.index-url   # 恢复默认

配置会写入用户级配置文件,之后所有 pip install 都走这个源。注意确认地址来源可靠,避免用到不可信的镜像。

第 3 步:导出并复用依赖

在开发完成、环境稳定的项目里导出当前依赖:

python -m pip freeze > requirements.txt

在另一台机器上用虚拟环境还原:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

pip freeze 会把环境里所有包都导出,包括间接依赖和工具包。如果只想导出顶层依赖,可借助 pip-tools 等工具从 requirements.in 编译生成,具体用法以官方文档为准。

第 4 步:检测版本冲突

安装后出现功能异常,先检查依赖是否一致:

python -m pip check

它会列出已安装包之间的版本冲突,比如"包 A 需要 requests<3,但装的是 3.x"。想看清依赖树,装一个小工具:

python -m pip install pipdeptree
pipdeptree --warn fail

pipdeptree 用树状结构展示谁依赖谁,--warn fail 让它在发现冲突时以非零状态退出,便于写进脚本。

第 5 步:解决冲突的固定套路

  1. 用 pip check 或 pipdeptree 找出冲突的两个包。
  2. 查清各自的版本要求,通常是某个包限制了另一个包的范围。
  3. 统一升级到兼容版本:python -m pip install -U 包名。
  4. 必须保留旧版本时,用 pip install "包名==具体版本" 精确安装。
  5. 重新 pip freeze > requirements.txt,把修正后的版本锁定下来。

三、关键细节

  1. 用 python -m pip 而不是直接 pip:前者明确使用当前解释器对应的 pip,避免"装到了另一个 Python 里"的经典问题。
  2. 务必在虚拟环境里操作:全局安装容易污染系统环境,且权限问题多。先 activate 再安装。
  3. pip freeze 会包含间接依赖:这是好事,能保证可复现;但如果环境里装了无关工具,要先清理或手工删掉无关行。
  4. == 才是真正锁定:>= 给升级留了空间,不利于复现;生产依赖推荐全部用 ==。
  5. 换源只改"从哪下载",不改版本解析规则:源里没有对应版本才会报找不到,别误以为是 pip 坏了。
  6. 升级要逐个来:一次性 -U 升级所有包,出问题很难定位是谁引起的。

四、常见错误

现象 原因 修正
装完包 import 仍报模块不存在 用 pip 装到了别的 Python,而运行用的是另一个解释器 统一用 python -m pip install
提示 Could not find a version 当前源里没有该包或该版本,包名拼错也常见 核对包名,换官方源或确认镜像同步情况
报权限错误 Permission denied 往系统目录安装且没有写权限 在虚拟环境里安装,或按提示加用户级安装选项
昨天能跑今天报错 依赖没锁定,pip 装了新版本 用 == 锁定版本并保存 requirements.txt
pip check 报版本冲突 两个包对同一依赖的版本要求不一致 按第 5 步套路升级或回退到兼容版本
导出 requirements 后在别的机器装不上 原环境有系统级包或平台相关包,冻结结果不通用 在干净的虚拟环境中导出,必要时按平台分别维护

五、排查方法

  1. 先确认环境:依次执行 which python(Windows 用 where python)和 python -m pip --version,看解释器和 pip 是否匹配。
  2. 确认是否激活虚拟环境:看命令行提示符是否有环境名,或 python -c "import sys; print(sys.prefix)"。
  3. 看已安装包及版本:python -m pip list,与 requirements.txt 对比差异。
  4. 查冲突:python -m pip check,有输出就按提示逐个处理。
  5. 看依赖树:pipdeptree,找出是哪一层引入了不兼容版本。
  6. 验证来源:python -m pip config list 确认当前源;换回官方 PyPI 再装一次,排除源的问题。
  7. 彻底重建:删掉虚拟环境,用 requirements.txt 全新安装一次,能复现问题就说明是依赖问题而非环境残留。

六、注意事项

  • 包名、版本号、镜像地址都可能随时间变化,本文示例只演示方法,具体值请以官方仓库和各镜像站公告为准。
  • requirements.txt 适合简单项目;复杂项目可考虑 pyproject.toml + 锁文件方案,工具与用法以官方文档为准。
  • 不要混用多个包管理器(如 pip 与conda)随意安装同一环境,容易引发难查的冲突。
  • 从不可信的源安装包有安全风险,生产环境应优先使用官方源或经过审核的私服。
  • 升级后再跑一遍测试,版本锁定只保证"装得一样",不保证"行为不变"。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。