Jupyter Notebook导入自定义模块遇ModuleNotFoundError问题求助

文件结构 #

root/
├── tests/
├── src/
│   ├── __init__.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── data.py
│   │   └── pipeline.py
│   ├── sqlal/
│   │   ├── __init__.py
│   │   └── sql_alchm.py
│   └── test.py
└── process.ipynb

相关代码示例 #

data.py #

from abc import ABC

class DataStrategy(ABC):
    pass

test.py #

from utils.data import DataStrategy

class TestPipeline(DataStrategy):
    pass

问题场景 #

在process.ipynb中执行以下导入代码：

import os
from src.test import TestPipeline

# 单元格其余代码
.....
.....

出现错误：

ModuleNotFoundError: No module named 'utils'

但直接运行test.py时无此错误，疑问：该问题是否与Notebook作用域有关，或是遗漏了什么？

问题原因与解决方法 #

这个问题核心是Python模块搜索路径的差异，和Notebook的运行作用域直接相关：

原因分析 #

• 直接运行test.py时：Python会自动将脚本所在的src/目录加入模块搜索路径sys.path，所以from utils.data import...能找到同级的utils模块。
• 运行Jupyter Notebook时：Notebook默认工作目录是启动时所在的root/，sys.path默认包含root/而非src/。当加载src/test.py后，test.py里的from utils.data import...会从sys.path找utils，但utils在root/src/下，自然找不到。

解决方法 #

• 方法1：在Notebook中添加src目录到搜索路径
  在Notebook首个单元格执行：

  import sys
  sys.path.append('./src')
  

  之后再执行导入代码即可正常运行。

• 方法2：修改test.py为相对导入
  将test.py中的导入语句改为相对路径：

  from .utils.data import DataStrategy
  

  注意：此时直接运行test.py需使用模块方式，从root/目录执行python -m src.test。

• 方法3：统一搜索路径为root目录
  在Notebook中添加：

  import sys
  sys.path.append('.')
  

  同时修改test.py的导入语句为：

  from src.utils.data import DataStrategy
  

  这种方式能兼容Notebook和模块方式运行脚本。

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