WSL2中Jupyter Notebook导入utils模块报错：No module named 'utils'如何解决？

问题原因 #

Windows本地Python会自动将项目根目录（project）加入sys.path搜索路径，但WSL2的Python环境不会默认识别Windows侧的项目路径，导致找不到utils包。

解决方法 #

方法1：在Notebook中临时添加项目根路径 #

在notebook.ipynb开头加入代码，手动将project根目录添加到Python搜索路径：

import sys
from pathlib import Path

# 方式1：自动匹配目录结构获取根路径（notebook位于project/code/code_subfolder，需往上两级到project）
project_root = Path.cwd().parent.parent
sys.path.append(str(project_root))

# 方式2：直接指定WSL中的绝对路径（比如Windows项目在C:\Users\xxx\project，对应WSL路径为/mnt/c/Users/xxx/project）
# project_root = Path("/mnt/c/Users/xxx/project")
# sys.path.append(str(project_root))

from utils.helpers import *

注意：Path.cwd()获取的是Notebook运行时的工作目录，若你的工作目录不是code_subfolder，需调整parent的层级。

方法2：设置PYTHONPATH环境变量（永久生效） #

通过配置环境变量，让WSL的Python每次启动自动加载项目根路径：

1. 打开WSL终端，编辑shell配置文件（bash用~/.bashrc，zsh用~/.zshrc）：

   nano ~/.bashrc
   

2. 在文件末尾添加以下内容（替换为你的project在WSL中的绝对路径）：

   export PYTHONPATH="/mnt/c/Users/xxx/project:$PYTHONPATH"
   

3. 保存退出后，执行命令使配置生效：

   source ~/.bashrc
   

之后无论在哪个目录运行Python脚本，都能直接导入utils.helpers。

方法3：通过.pth文件添加路径（永久生效） #

在Python的site-packages目录中添加.pth文件，让Python自动识别项目根路径：

1. 先确认WSL中Python的site-packages目录：

   python3 -c "import site; print(site.getusersitepackages())"
   

2. 进入project目录，创建.pth文件并写入当前路径：

   cd /mnt/c/Users/xxx/project
   echo "$PWD" > $(python3 -c "import site; print(site.getusersitepackages())")/project_root.pth
   

重启Python后即可直接导入utils模块。

额外检查 #

确保utils目录下存在空的__init__.py文件（Python3.3+支持无该文件的命名空间包，但部分环境仍需此文件确认包身份），若没有，直接在utils目录新建一个空文件即可。

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