安装Editable模式Python包后无法导入模块的问题求助

项目结构 #

root\
  .git\
  server\
     setup.py
     company\
        __init__.py
        zed\
            __init__.py
            server\
                __init__.py
                server.py
                util.py

所有__init__.py文件均为空。

setup.py内容 #

from setuptools import setup, find_packages

setup(
    name="zed-server",
    version="1.0.0",
    packages=find_packages(),
    install_requires=[
        # ...
    ]
)

已确认find_packages()返回：

['company', 'company.zed', 'company.zed.server']

安装情况 #

通过以下命令以可编辑模式安装包：

cd root\server
pip install -e .

pip list确认包已安装为可编辑模式：

$ pip list
...
zed-server          1.0.0     C:\path\to\root\server
...

报错情况 #

server.py中有导入语句：

import company.zed.server.util

通过以下方式运行文件：

cd root\server\company\zed\server
python server.py

执行失败，报错：

ModuleNotFoundError: No module named 'company.zed.server'

系统环境：

• Windows 10
• Python 3.11.1
• Pip 23.3.1
• Setuptools 68.2.2

核心问题：脚本运行时的sys.path上下文错误 #

当直接运行server.py脚本时，Python会自动将脚本所在目录（root\server\company\zed\server）加入sys.path的最前端。虽然通过可编辑安装将root\server加入了Python的包搜索路径，但存在两种可能导致导入失败：

1. Python环境不匹配：用于运行脚本的Python解释器，和执行pip install -e .的pip不属于同一个环境（比如未激活虚拟环境，或混用了python/python3/conda环境），导致root\server并未被加入当前运行环境的sys.path。
2. 脚本运行模式的路径优先级：即使root\server在sys.path中，Python查找company包时会优先在sys.path前端目录（脚本所在目录）查找，该目录下不存在company文件夹，若后续路径未正确加载root\server，就会抛出找不到模块的错误。

方法1：以模块方式运行（推荐） #

从root\server目录下，通过Python的模块运行命令启动，这种方式会自动将当前目录（包的根目录）加入sys.path，符合Python包规范：

cd root\server
python -m company.zed.server.server

方法2：手动修正sys.path #

在server.py的最顶部添加代码，将包的根目录（root\server）加入sys.path：

import sys
from pathlib import Path

# 获取root\server目录的绝对路径
package_root = Path(__file__).parent.parent.parent.parent
sys.path.append(str(package_root))

# 后续导入语句
import company.zed.server.util

方法3：确认Python环境一致性 #

检查运行脚本的Python解释器和安装包的pip是否属于同一环境：

1. 查看pip对应的Python路径：

   pip --version
   

2. 查看运行脚本的Python路径：

   python --version
   

3. 如果路径不一致，切换到对应的环境（比如激活虚拟环境），或使用python -m pip install -e .确保安装到当前Python环境中。

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