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
相关产品推荐
相关产品推荐

