You need to enable JavaScript to run this app. Python同目录导入自定义utilities.py报ModuleNotFoundError求解决
优惠活动
大模型
产品
解决方案
定价
更多

Python同目录导入自定义utilities.py报ModuleNotFoundError求解决

同目录自定义模块导入报ModuleNotFoundError: No module named 'utilities'的排查方案

Python自定义模块的核心导入逻辑

Python执行import 模块名语句时,不会自动扫描硬盘上的所有文件夹匹配目标文件,而是严格按照固定顺序遍历预定义的模块搜索路径列表,找到第一个匹配的文件才会完成加载。这个搜索路径列表的常见组成部分包括:

  • 启动Python解释器时的当前工作目录(注意:这是终端执行命令时所在的目录,不是你写的调用脚本本身存储的目录)
  • Python解释器内置的标准库安装目录
  • 第三方包安装所在的site-packages目录
  • 系统环境变量PYTHONPATH中配置的所有目录
    很多新手遇到这类报错的核心原因,就是默认认为“两个文件存放在同一个文件夹里就一定会被导入逻辑识别”,这和Python实际的搜索规则是不匹配的。

分步排查解决流程

1. 先定位最常见的工作目录问题

  • 在你的调用脚本最顶部加两行临时调试代码,打印当前Python实际加载的搜索路径:
import sys
print(sys.path)
  • 运行脚本后检查输出的路径列表,确认列表中是否包含utilities.py实际所在的文件夹绝对路径
  • 做个快速验证:打开终端,手动切换到两个Python文件共同存放的目录,再在这个目录下执行python 你的调用脚本名称.py。如果这个操作下导入正常,说明之前的报错完全是运行时的工作目录不对导致的——这也是90%同类报错的原因。

2. 排除基础常识类错误

如果切换工作目录后还是报错,检查以下几个易忽略的问题:

  • 文件名是否准确:确认utilities.py没有被误存为类似utilitiez.py、utilities.txt、utilities.py.py这类带隐藏后缀的错误文件名
  • 模块名是否和Python内置标准库重名:如果你的文件和os.py、random.py这类内置模块重名,导入逻辑会优先匹配内置模块,自己写的文件会被自动遮蔽
  • Python解释器环境是否匹配:如果你的电脑上有多个Python版本(比如全局Python、虚拟环境),确认你运行脚本用的解释器,和你写代码、调试时用的是同一个环境

3. 长期通用的解决方法

如果不想每次运行脚本都手动切换到对应目录,可以选择以下任意一种一劳永逸的方案:

  • 方案1:在调用脚本的最顶部自动把当前脚本所在的目录加入搜索路径,不管从哪个工作目录启动脚本都能正常找到同文件夹下的模块:
import sys
from pathlib import Path
# 自动获取当前调用脚本所在的绝对路径,插入到搜索路径最前面
sys.path.insert(0, str(Path(__file__).resolve().parent))
import utilities
  • 方案2:把utilities.py所在的目录添加到系统PYTHONPATH环境变量中,所有Python进程启动时都会自动把这个目录加入搜索路径,适合需要在多个项目中复用这个工具脚本的场景
  • 方案3:按照Python标准包的规范,把工具脚本打包为可安装的本地包,像pip安装的第三方库一样安装到当前Python环境中,适合长期维护、跨项目复用的代码

注意:很多人发现用IDE(比如PyCharm、VSCode)写代码时导入不会报错,换终端手动运行就会失败,本质是IDE在运行脚本时,自动把脚本所在的目录设置为了当前工作目录,手动运行时没有触发这个配置,并不是IDE自带什么特殊的导入逻辑。

内容的提问来源于stack exchange,提问作者Ciccios_1518

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.02 09:45:11