Linux下pip install --editable安装成功但pip list无显示如何解决

排查步骤 #

• 先校验pip与Python解释器的环境匹配度
  这是最高发的诱因：多版本Python、多虚拟环境（conda/venv/系统Python）共存时，执行pip install用的是A环境的pip，后续执行pip list用的是B环境的pip，自然查不到。
  校验方式：分别执行which pip、which python，确认两个二进制文件属于同一环境目录。不要直接调pip命令，后续所有操作都用python -m pip的方式调用当前解释器绑定的pip，从根源避免路径错位。
• 检查项目打包配置合规性
  可编辑（editable）模式对打包配置的校验比普通安装严格，普通安装能成功不代表配置满足editable模式要求：
  • 确认项目根目录存在合法打包配置：要么是符合PEP规范的pyproject.toml，要么是传统的setup.py/setup.cfg，缺失配置文件会导致安装流程静默异常。
  • 检查setuptools版本：低于64.0版本的setuptools对PEP660（新版editable安装标准）支持存在已知bug，会出现返回安装成功但不写入包元数据的问题。
  • 核对包路径映射：确认配置中packages字段正确指向源码目录，源码目录下存在__init__.py文件，路径映射错误时editable模式不会像普通安装那样自动拷贝源码到site-packages，会直接导致包不可见。
• 检查site-packages内的安装记录是否正常
  执行python -m site拿到当前环境的site-packages目录绝对路径，进入目录查找两类editable安装生成的标记文件：
  1. 传统setuptools模式生成的<包名>.egg-link文件
  2. 新版PEP660模式生成的__editable__.<包名>.pth文件
  • 如果找不到对应标记文件，大概率是权限问题：当前用户对site-packages目录没有写入权限，安装流程没有抛出硬错误但元数据写入被静默截断，常见于混用sudo安装、全局Python目录安装的场景。
  • 如果能找到标记文件，查看文件内记录的源码绝对路径是否和你实际的代码目录一致，安装后挪动代码位置、安装时填错相对路径都会导致路径失效。
• 排查包名冲突
  检查待安装的包名是否和Python标准库、已安装的其他第三方包重名，editable安装的包如果和已有同包名记录冲突，会被已有条目覆盖，pip list不会显示重复项。

解决方案 #

• 基础修复流程（覆盖80%以上场景）：
  先升级基础打包组件，再用解释器直调pip的方式重新安装，最后校验结果：

  python -m pip install -U pip setuptools wheel
  python -m pip install -e /path-to-code
  python -m pip list | grep 你的包名
  

• 旧项目兼容方案：
  如果是基于传统setup.py的老项目，新版editable模式兼容有问题时，可以加兼容参数强制走传统egg-link模式安装，绕开PEP660的兼容问题：

  python -m pip install -e /path-to-code --config-settings editable_mode=compat
  

• 权限问题修复：
  不要用sudo执行pip安装，优先在个人目录下创建venv/conda虚拟环境，激活虚拟环境后再执行安装，避免全局目录的权限限制导致元数据写入失败。
• 配置问题修复：
  补全pyproject.toml内的build-system配置，修正packages字段的路径映射，确保源码目录存在合法的__init__.py文件。
• 冲突问题修复：
  先执行python -m pip uninstall <包名>清理掉所有同包名的历史安装残留，再重新执行editable安装。

内容的提问来源于stack exchange，提问作者WurmD