分布式Yarn容器JupyterLab导入自定义模块报ModuleNotFoundError

AI 小北

2026-8-28

Yarn容器下JupyterLab自定义.py模块导入失败排查方案

所有导入失败的核心逻辑只有一个：当前运行Notebook代码的Python进程，没有把你存放模块的src目录纳入模块搜索路径sys.path。你之前在Bash终端设置变量、在Notebook里改os.environ['PYTHONPATH']的操作不生效，本质是环境变量作用域和加载时机不对——Python进程启动时就会完成sys.path的初始化，事后在独立Shell里改变量、在进程运行时改PYTHONPATH环境变量，都不会更新已经加载完成的模块搜索列表。

按以下顺序排查，每步做完直接验证即可：

第一步：先拿到当前内核的真实运行参数，不要靠终端echo的结果猜
新开一个Notebook单元格执行以下代码，打印当前环境的真实状态：
```
import sys
import os
print(f"当前Python解释器路径: {sys.executable}")
print(f"当前Notebook工作目录: {os.getcwd()}")
print("当前生效的模块搜索路径列表:")
for idx, path in enumerate(sys.path):
    print(f"  {idx}. {path}")
```
注意：Python查找模块完全以sys.path的内容为准，不在这个列表里的目录，就算你在终端里把PYTHONPATH写得再对，也会报ModuleNotFoundError。
第二步：排查路径本身的有效性
你之前写的硬编码Yarn路径带{user}/{application_id}这类占位符，不会被自动替换为实际值，属于无效路径。直接在Notebook里动态校验src目录的真实状态：
```
# 按你的实际目录位置调整，这里默认src在当前Notebook工作目录下
src_abs_path = os.path.abspath("./src")
print(f"src目录绝对路径: {src_abs_path}")
print(f"src目录是否存在: {os.path.exists(src_abs_path)}")
print(f"src目录下__init__.py是否存在: {os.path.exists(os.path.join(src_abs_path, '__init__.py'))}")
```
只要后两个打印结果有一个是False，先修正路径、补全/重命名正确的__init__.py文件（注意文件名是双下划线前后包裹，常见笔误有__init.py、init.py、__init__.py.txt）。

第三步：用直接修改sys.path的方式临时修复，验证导入逻辑
不要在Notebook里通过改os.environ['PYTHONPATH']的方式加路径，这种方式不会触发sys.path更新。直接在导入自定义模块的单元格之前，执行以下代码把src目录插入搜索路径头部：

import sys
import os
src_abs_path = os.path.abspath("./src")
# 避免重复添加路径
if src_abs_path not in sys.path:
    sys.path.insert(0, src_abs_path)
# 验证路径已加入
print(f"src路径已纳入搜索范围: {src_abs_path in sys.path}")
# 验证模块可被发现
import importlib.util
print(f"目标模块可被检索到: {importlib.util.find_spec('你的模块名') is not None}")

这一步执行完如果最后一行打印True，就可以正常执行导入操作。

第四步：排查配置不持久、环境不匹配的问题
如果你不想每次开Notebook都手动加路径，或者第三步执行完还是失败，检查两个常见配置错位问题：
1. Bash配置和Jupyter内核不在同一个进程上下文：Yarn容器内JupyterLab一般是容器启动阶段就拉起的常驻进程，你事后新开的Bash终端是独立的Shell进程，在里面执行export、conda env config vars set设置的变量，不会同步给已经运行的Jupyter内核，哪怕重启内核也不一定能读到——conda设置的环境变量只有在设置完成后，从对应Shell会话启动的Python进程才会加载。
  要做永久生效的配置，可以在Jupyter启动脚本里加路径，或者在IPython的启动目录下创建自动执行脚本：执行jupyter --paths找到用户配置目录，在<配置目录>/ipython/profile_default/startup/下新建00_add_src_path.py，把第三步里加sys.path的代码写进去，所有内核启动时会自动执行这段逻辑。
2. Conda环境和Jupyter内核不匹配：对比第一步打印的sys.executable路径和你在Bash里配置conda环境用的Python路径，如果路径不一致，说明Jupyter当前用的内核不是你配置过变量的那个conda环境。切到对应环境执行python -m ipykernel install --user --name=你的环境名，把环境注册为Jupyter内核，重启Jupyter后选择对应内核即可。

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