一、基础知识
先认识几个名词: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 步:解决冲突的固定套路
- 用
pip check或pipdeptree找出冲突的两个包。 - 查清各自的版本要求,通常是某个包限制了另一个包的范围。
- 统一升级到兼容版本:
python -m pip install -U 包名。 - 必须保留旧版本时,用
pip install "包名==具体版本"精确安装。 - 重新
pip freeze > requirements.txt,把修正后的版本锁定下来。
三、关键细节
- 用
python -m pip而不是直接pip:前者明确使用当前解释器对应的 pip,避免"装到了另一个 Python 里"的经典问题。 - 务必在虚拟环境里操作:全局安装容易污染系统环境,且权限问题多。先
activate再安装。 pip freeze会包含间接依赖:这是好事,能保证可复现;但如果环境里装了无关工具,要先清理或手工删掉无关行。==才是真正锁定:>=给升级留了空间,不利于复现;生产依赖推荐全部用==。- 换源只改"从哪下载",不改版本解析规则:源里没有对应版本才会报找不到,别误以为是 pip 坏了。
- 升级要逐个来:一次性
-U升级所有包,出问题很难定位是谁引起的。
四、常见错误
| 现象 | 原因 | 修正 |
|---|---|---|
装完包 import 仍报模块不存在 |
用 pip 装到了别的 Python,而运行用的是另一个解释器 |
统一用 python -m pip install |
提示 Could not find a version |
当前源里没有该包或该版本,包名拼错也常见 | 核对包名,换官方源或确认镜像同步情况 |
报权限错误 Permission denied |
往系统目录安装且没有写权限 | 在虚拟环境里安装,或按提示加用户级安装选项 |
| 昨天能跑今天报错 | 依赖没锁定,pip 装了新版本 | 用 == 锁定版本并保存 requirements.txt |
pip check 报版本冲突 |
两个包对同一依赖的版本要求不一致 | 按第 5 步套路升级或回退到兼容版本 |
| 导出 requirements 后在别的机器装不上 | 原环境有系统级包或平台相关包,冻结结果不通用 | 在干净的虚拟环境中导出,必要时按平台分别维护 |
五、排查方法
- 先确认环境:依次执行
which python(Windows 用where python)和python -m pip --version,看解释器和 pip 是否匹配。 - 确认是否激活虚拟环境:看命令行提示符是否有环境名,或
python -c "import sys; print(sys.prefix)"。 - 看已安装包及版本:
python -m pip list,与requirements.txt对比差异。 - 查冲突:
python -m pip check,有输出就按提示逐个处理。 - 看依赖树:
pipdeptree,找出是哪一层引入了不兼容版本。 - 验证来源:
python -m pip config list确认当前源;换回官方 PyPI 再装一次,排除源的问题。 - 彻底重建:删掉虚拟环境,用
requirements.txt全新安装一次,能复现问题就说明是依赖问题而非环境残留。
六、注意事项
- 包名、版本号、镜像地址都可能随时间变化,本文示例只演示方法,具体值请以官方仓库和各镜像站公告为准。
requirements.txt适合简单项目;复杂项目可考虑pyproject.toml+ 锁文件方案,工具与用法以官方文档为准。- 不要混用多个包管理器(如 pip 与conda)随意安装同一环境,容易引发难查的冲突。
- 从不可信的源安装包有安全风险,生产环境应优先使用官方源或经过审核的私服。
- 升级后再跑一遍测试,版本锁定只保证"装得一样",不保证"行为不变"。
免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。

评论
还没有评论,来说两句吧。