Python editable install 更新 怎样处理

我第一次连续改 Python 项目时，最容易误判的是“代码已经保存，为什么命令行还像旧版本”。如果项目是通过 editable install 安装的，源码变化和项目安装元数据变化并不是一回事：前者通常只要重新启动解释器进程，后者则需要再次执行安装命令。

官方资料：https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/、https://pip.pypa.io/en/stable/topics/local-project-installs/、https://setuptools.pypa.io/en/latest/userguide/development_mode.html。

先看你改的是哪一层：只改 Python 源码，通常重启解释器即可；改了版本、依赖、入口脚本、包发现配置或非 Python 扩展，就重新执行 python -m pip install -e .，涉及编译扩展时还要重新构建。

先把 editable install 装进正确的环境

editable install 解决的是开发目录和当前 Python 环境之间的连接。它不会把项目复制成一个普通发布包，而是让解释器能够从开发目录加载包。因此我排查“更新没有生效”时，第一步不是加 --upgrade，而是确认命令使用的是同一个虚拟环境。

# 在项目根目录执行，确保 pip 隶属于当前 python
python -m pip --version
python -c "import sys; print(sys.executable)"

# 首次把当前项目以 editable 方式安装到这个环境
python -m pip install -e .

把 python 和 pip 写成同一条 python -m pip 链路，能减少系统 Python、虚拟环境和 IDE 解释器混用的问题。若项目已经安装过，直接再次执行同一条命令就是最稳妥的刷新入口。

源码改动和安装元数据改动要分开判断

只改包目录里的 Python 源码时，editable install 通常会让下一次启动的解释器直接读取新文件。正在运行的进程不会自动重载已经导入的模块，所以服务、REPL 或测试进程仍然需要重启。

下面这些变化则应该重新安装：项目版本、依赖声明、可执行入口点、包发现规则、构建后端配置，以及会影响生成文件的项目元数据。依赖声明更新后，是否需要同时升级依赖，要由项目约束和当前环境决定，不能把 --upgrade 当成所有问题的默认答案。

# 修改 pyproject.toml、依赖或入口点后，刷新 editable 安装
python -m pip install -e .

# 只有明确要让直接依赖尝试更新时才使用 --upgrade
python -m pip install -e . --upgrade

# 不希望这次安装改动依赖集合时，显式跳过依赖安装
python -m pip install -e . --no-deps

这三条命令的目的不同：第一条重建当前项目的 editable 安装；第二条把依赖升级意图也交给解析器；第三条只刷新项目本身。团队脚本里最好把选择写清楚，避免一次“更新代码”的操作顺手改动整个环境。

遇到新文件、资源和扩展模块时别只重启

editable install 对 Python 模块最友好，但它不保证所有非 Python 文件都像源码一样实时可见。新增包文件、资源文件、控制台脚本和项目元数据，可能需要重新安装；C、C++ 或其他二进制扩展则需要执行项目规定的构建命令。

如果使用 setuptools 的 strict editable 模式，安装可能在项目目录下生成 build/__editable__.* 一类辅助目录，并通过链接或导入机制尽量模拟普通安装。strict 模式更接近发布形态，但新增文件不会自动暴露，改动后要把“重新安装”纳入工作习惯。

# 需要更接近普通安装行为时，可按项目构建后端选择 strict 模式
python -m pip install -e . --config-settings editable_mode=strict

# 非 Python 扩展由项目自己的构建系统负责；命令名称以项目文档为准
# 下面只表示占位示例，不代表所有项目都使用同一命令
python -m build

python -m build 不是每个项目都必须执行的固定步骤；重点是识别“源码导入”和“构建产物”这两个不同生命周期。不要删除 strict 模式生成的辅助目录后再猜测导入失败原因，若要清理，应先卸载对应项目。

发布前用普通安装复查一次

editable install 适合开发迭代，不适合代替 CI 或部署验证。pip 官方建议在需要接近真实分发行为的场景使用普通安装，因为 editable 模式和 wheel 安装可能暴露不同的文件集合和路径行为。

我的判断清单是：只改 Python 源码，重启进程；改 pyproject.toml、版本、依赖或入口点，重新执行 editable install；改非 Python 扩展，重新构建；准备发布时构建 wheel 并在干净环境普通安装。这样每次更新都有明确动作，不会靠反复重启碰运气。

常见问题

改了 Python 文件却没有生效，第一步查什么？

先确认运行进程使用的解释器和你执行 python -m pip install -e . 的解释器相同，再重启进程。editable install 不会让已经导入的模块自动热更新。

修改依赖版本后只重启程序可以吗？

不可以把它当成可靠做法。依赖声明属于项目元数据，应该重新执行 editable install；是否升级到新版本，还要看版本约束、锁定文件和团队的依赖策略。

为什么 editable 环境能运行，普通安装却缺文件？

两种安装方式暴露文件的规则可能不同，尤其是包发现、数据文件和非 Python 资源。发布前构建并安装 wheel，才能更早发现没有被分发配置纳入的文件。