Python模块导入失败排查：utils模块找不到的解决方法

1. 确认utils.py的实际位置 #

• 先定位项目根目录（从你的命令路径看是/Users/pitosalas/mydev/public-131-samples/memsim/memsim/），检查utils.py是否在该根目录下，还是在tests子目录之外的其他位置。比如常见结构是根目录存utils.py，tests作为子目录，这种情况下直接from utils import...会找不到模块。

2. 检查Python的模块搜索路径 #

• 在hypothesis_test.py开头添加以下代码，打印当前Python可识别的模块路径：

  import sys
  print(sys.path)
  

• 运行脚本后，查看输出里是否包含utils.py所在的目录。如果没有，说明该目录不在Python的搜索范围内。

3. 临时添加模块路径到sys.path #

• 若确认utils.py在项目根目录（和tests同级），可在导入前手动添加路径：

  import sys
  from pathlib import Path
  # 获取当前脚本的父目录的父目录（即项目根目录）
  project_root = Path(__file__).parent.parent
  sys.path.append(str(project_root))
  from utils import collapse_contiguous_ranges, check_number_in_range
  

• 这种方法适合临时测试，能快速验证是否为路径问题。

4. 使用相对导入（适配包结构） #

• 如果你的项目是标准Python包（根目录下存在__init__.py文件），可以用相对导入：

  from ..utils import collapse_contiguous_ranges, check_number_in_range
  

• 注意：相对导入仅在项目作为包运行时生效，不能直接单独运行脚本，需用python -m memsim.tests.hypothesis_test这种方式执行。

5. 设置PYTHONPATH环境变量 #

• 运行脚本前，将项目根目录加入PYTHONPATH：

  # macOS/Linux环境
  export PYTHONPATH="/Users/pitosalas/mydev/public-131-samples/memsim/memsim:$PYTHONPATH"
  python -u "/Users/pitosalas/mydev/public-131-samples/memsim/memsim/tests/hypothesis_test.py"
  

• 该方式会让当前终端会话内的Python永久识别该目录，适合频繁测试的场景。

6. 校验utils.py的文件名与拼写 #

• 检查utils.py的文件名是否正确，有没有拼写错误（比如写成Util.py或utils_.py），Python在macOS/Linux环境下对文件名大小写敏感。

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