Python模块导入故障：目录变更后导入失败及长效解决方案咨询

问题背景 #

项目结构：

MYPROJECT
|
-- src
    |
   -- data
       __init__.py
       basic_script.py
   -- utils
      __init__.py
      some_utils.py

终端根目录为c:\some_path\MYPROJECT，执行命令python src/data/basic_script.py运行文件时，报错ModuleNotFoundError: No module named 'utils'，当前sys.path仅包含Python版本路径及虚拟环境路径。

1. 需要添加到sys.path的内容 #

需要将项目的src目录绝对路径加入sys.path，也就是c:\some_path\MYPROJECT\src。

临时修复可在basic_script.py开头添加以下代码：

import sys
from pathlib import Path

# 自动获取src目录的绝对路径
src_path = Path(__file__).parent.parent.parent / "src"
sys.path.append(str(src_path.resolve()))

import utils.some_utils as some_utils

2. 最优解决方案及替代方案 #

手动修改sys.path不是长期最优解，推荐以下两种规范方式：

方式一：相对导入+模块模式运行

把basic_script.py中的导入语句改为相对导入：

from ..utils import some_utils

然后在终端（MYPROJECT根目录）用模块模式运行脚本：

python -m src.data.basic_script

这种方式让Python将项目根目录视为包的起始点，自动识别导入层级，无需手动调整路径。

方式二：设置PYTHONPATH环境变量

运行脚本前先通过环境变量把src目录加入Python路径：

• Windows终端：

set PYTHONPATH=c:\some_path\MYPROJECT\src
python src/data/basic_script.py

• Linux/macOS终端：

export PYTHONPATH=/path/to/MYPROJECT/src
python src/data/basic_script.py

无需修改代码，适合临时调试场景。

3. 跨系统迁移的保障方案（通过setup.py实现） #

可以通过setup.py将项目打包为可安装的Python包，跨系统迁移时自动配置路径，步骤如下：

1. 在MYPROJECT根目录创建setup.py文件，内容如下：

from setuptools import setup, find_packages

setup(
    name="myproject",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
)

2. 在终端（MYPROJECT根目录）执行命令，以可编辑模式安装项目：

pip install -e .

安装完成后，Python会自动将项目src目录加入sys.path，无论在哪个路径下运行脚本，都能直接使用import utils.some_utils as some_utils的导入语句。跨系统迁移时，只需重新执行上述安装命令即可。

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