pip install 命令完整区别拆解
深入理解 pip install -r requirements.txt 与 pip install -r requirements.txt -e . 的差异、原理与适用场景
一、命令拆分说明
命令 A：pip install -r requirements.txt
等价于两步操作：
- 读取
requirements.txt中列出的所有第三方库（如 pytest、numpy、python-dotenv 等） - 批量下载并安装这些外部依赖包到当前 Python 环境
命令 B：pip install -r requirements.txt -e .
拆成三部分：
-r requirements.txt— 同命令 A，安装所有第三方依赖.— 代表当前项目根目录（即包含pyproject.toml/setup.cfg的目录，即本地代码包，如borehole_extractor）-e（=--editable）— 可编辑模式安装本地项目
关键理解
命令 B = 命令 A 的全部功能 + 以可编辑方式安装本地项目代码包。它不是替换关系，而是包含关系。
二、核心区别对照表
| 对比维度 | 命令 A：仅 -r |
命令 B：-r + -e . |
|---|---|---|
| 安装内容 | 只安装第三方依赖，不安装项目代码包本身 | 先装所有第三方依赖，再以可编辑模式安装本地 borehole_extractor 包 |
| 代码修改生效 | 修改项目源码后，环境中的代码不会自动更新，导入时仍是旧版本 | 本地源码实时生效，改完代码无需重新安装，直接生效 |
| 模块导入 | 运行 import borehole_extractor 会报错 ModuleNotFoundError |
任意位置都能正常 import borehole_extractor，像第三方库一样使用 |
| 适用人群 | 仅临时运行脚本、不修改项目源码的用户 | 开发、修改源码、调试、跑单元测试的开发者 |
| 底层原理 | 仅从 PyPI 下载线上包到 site-packages | 创建软链接（.pth 文件）指向本地项目文件夹，环境直接读取本地源码 |
| 运行测试 | 失败 pytest 找不到项目模块 | 通过 pytest 正常识别并测试 |
| 运行示例 | 失败 examples/ 脚本导入报错 | 通过 examples/ 正常执行 |
三、直观场景演示
场景 1：只执行命令 A
✗ 尝试导入项目模块
>>> import borehole_extractor
ModuleNotFoundError:
No module named 'borehole_extractor'✗ 运行单元测试
$ pytest tests/
ERROR: cannot resolve 'borehole_extractor'
-- no such module in environment
原因
requirements.txt 只记录第三方库（如 numpy、pytest），不会将本地项目注册为 Python 包。Python 解释器根本不知道 borehole_extractor 这个模块的存在。
场景 2：执行命令 B
✓ 正常导入项目模块
>>> import borehole_extractor
# 成功！修改源码后再次运行立刻生效✓ 运行单元测试
$ pytest tests/
===== 12 passed in 0.45s =====
原理
-e . 在 site-packages 中创建了一个指向你项目根目录的链接文件（.pth）。Python 导入时直接走本地源码，因此修改代码后无需重装，即刻生效。
四、-e . 的前置条件与注意事项
必须满足的条件
项目根目录必须包含以下文件之一（任选其一即可），pip 才能识别这是一个可安装的 Python 包：
| 文件 | 状态 | 说明 |
|---|---|---|
pyproject.toml | 推荐 | 现代 Python 项目标准（PEP 517/518），当前项目已包含 |
setup.cfg | 可选 | setuptools 配置文件，当前项目也已包含 |
setup.py | 可选 | 传统方式，已逐步被 pyproject.toml 替代 |
项目状态确认
若项目同时包含
pyproject.toml 和 setup.cfg，完全满足条件，可以直接使用 -e .。
能否分开执行？
可以。命令 B 本质上是两步合并，拆开写效果完全一样：
# 等价写法：分两步
pip install -r requirements.txt # 第一步：安装第三方依赖
pip install -e . # 第二步：可编辑安装本地项目包
# 等价写法：合并一步
pip install -r requirements.txt -e .何时只用命令 A 即可？
- 仅下载别人的成品脚本，不修改源码
- 项目不需要作为 Python 库被
import（纯单文件脚本项目） - 部署到生产环境时（生产环境通常用
pip install .而非-e .）
五、-e .（Editable Install）底层原理
执行 pip install -e . 时，pip 并不会把源码复制到 site-packages 目录，而是：
- 读取
pyproject.toml（或setup.cfg）中的包名和入口配置 - 在 site-packages 中创建一个
.pth链接文件，指向项目根目录 - 运行
python -c "import borehole_extractor"时，解释器通过.pth文件找到本地源码路径，直接加载本地文件
类比理解
命令 A 好比”买了一本打印好的书”（复制到书架），改了原稿书架上不会变；
命令 B 好比”在书架上放了一张便签，写着’去作者桌上读最新稿'”，作者每次改稿你读到的都是最新版。
命令 B 好比”在书架上放了一张便签，写着’去作者桌上读最新稿'”，作者每次改稿你读到的都是最新版。
一句话总结
pip install -r requirements.txt
只装第三方工具库，不安装项目代码本身
pip install -r requirements.txt -e .
第三方库 + 本地项目代码一起安装，支持实时修改调试，开发专用
开发场景推荐
若需要修改
borehole_extractor 源码、运行 pytest tests/、执行 examples 示例，必须使用带 -e . 的完整命令，否则会频繁出现 ModuleNotFoundError。