Python可编辑包导入异常：testme.ipynb无法导入mattlibrary

项目结构 #

PYTHON_DEVELOPMENT [WSL: UBUNTU2504]
├── mattlibrary
├── test_bench
│   └── testme.ipynb
└── test.ipynb

问题描述 #

在testme.ipynb中执行import mattlibrary时提示模块未找到，但test.ipynb中导入正常。已知test.ipynb能成功导入是因为其当前工作目录（cwd）为PYTHON_DEVELOPMENT，可直接找到mattlibrary，且该包已以可编辑模式安装到虚拟环境中。

环境信息 #

sys.path 输出 #

['/usr/lib/python313.zip',
 '/usr/lib/python3.13',
 '/usr/lib/python3.13/lib-dynload',
 '',
 '/home/matt/development/python_development/.venv/lib/python3.13/site-packages']

虚拟环境site-packages目录文件 #

-rw-r--r--   2 matt matt     93 Jun 18 18:12 __editable__.mattlibrary-0.1.0.pth
-rw-r--r--   2 matt matt   3918 Jun 18 18:12 __editable___mattlibrary_0_1_0_finder.py

用户疑问 #

尝试多种方法后，仍无法在mattlibrary目录层级之外的位置导入该库，且不想每次导入都使用sys.path.insert。原本以为安装到虚拟环境后，项目内任何文件都能导入，怀疑sys.path中的空路径''是问题所在？为何导入时不搜索site-packages目录？哪里操作出错了？

解决方案 #

问题根源 #

1. 可编辑安装路径错误：如果执行pip install -e .时的工作目录不是PYTHON_DEVELOPMENT（mattlibrary的父目录），生成的.pth文件可能写入相对路径，导致子目录下的notebook无法识别。
2. 空路径''的影响：空路径代表当前工作目录，testme.ipynb的cwd是test_bench，所以空路径指向该目录，自然找不到mattlibrary，但这不是核心问题，核心是可编辑安装的配置是否正确。
3. site-packages搜索逻辑：Python一定会搜索sys.path中的site-packages目录，问题出在可编辑安装生成的文件是否正确指向mattlibrary的绝对路径。

修复步骤 #

• 重新执行可编辑安装：激活虚拟环境，切换到PYTHON_DEVELOPMENT目录，执行：

  pip install -e .
  

  这会让.pth文件写入mattlibrary的绝对路径，确保任何子目录下的脚本都能通过site-packages找到该包。
• 检查.pth文件内容：打开__editable__.mattlibrary-0.1.0.pth，确认里面是mattlibrary的绝对路径。如果是相对路径，说明之前安装时工作目录错误，重新安装即可解决。
• 验证虚拟环境一致性：在testme.ipynb中执行以下代码，确认使用的是安装了可编辑包的虚拟环境：

  import sys
  print(sys.executable)
  

  如果输出不是虚拟环境的Python路径，需要在Jupyter中切换到对应虚拟环境的内核。

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