Python读取图片报错FileNotFoundError怎么解决
详细解析在Python中使用Pillow、OpenCV或Matplotlib读取图片时出现FileNotFoundError的原因与排查方法,提供基于当前工作目录、pathlib与绝对路径的完整解决方案及避坑指南。
FileNotFoundError: [Errno 2] No such file or directory 时,最直接的原因是解释器根据当前路径规则未在磁盘上检索到对应名称的文件。绝大多数情况并非文件不存在,而是运行时工作目录与代码文件位置不一致、系统隐藏了实际扩展名或反斜杠转义错误。解决该问题的标准做法是使用 pathlib 锚定当前脚本所在目录构造绝对路径。
一、为什么文件明明在同级目录还会报错?
初学者在读取本地图片时,最常编写类似 Image.open("cat.jpg") 的代码。当图片与 Python 代码存放在同一个文件夹中,但程序依然抛出 FileNotFoundError 时,很多人会感到困惑。这背后的核心机制是“当前工作目录(Current Working Directory,CWD)”与“脚本所在文件目录”并不等价。
在 Python 中,所有裸相对路径(如 "cat.jpg" 或 "./images/cat.jpg")都是相对于终端执行命令时所在的目录进行解析的,而不是代码文件自身存储的目录。
- 如果你在项目根目录
/my_project/下执行了python src/app.py,那么 Python 的当前工作目录是/my_project/。 - 代码里的
Image.open("cat.jpg")会在/my_project/cat.jpg寻找文件,而你的图片实际位于/my_project/src/cat.jpg。 - 两者路径不匹配,系统内核便会向 Python 抛出底层系统错误
[Errno 2] No such file or directory。
二、四步系统排查法
当程序发生报错时,切忌盲目地在路径字符串中乱加 ../ 或多次重命名文件。建议按照以下由浅入深的步骤逐步排查:
步骤 1:打印当前工作目录与目标文件的完整绝对路径
在尝试打开图片的代码之前,先插入两行调试代码,直接将 Python 当前眼中的路径与目标文件的绝对路径打印出来:
import os
image_name = "cat.jpg"
print("【调试信息】当前工作目录 (CWD):", os.getcwd())
print("【调试信息】相对路径解析后的绝对路径:", os.path.abspath(image_name))
查看终端输出的绝对路径,复制该路径在系统终端或文件资源管理器中查找,通常会瞬间发现路径缺失了某个子目录层级。
步骤 2:检查文件扩展名是否被系统隐藏
在 Windows 操作系统中,系统默认开启了“隐藏已知文件类型的扩展名”选项。许多用户下载或创建图片后,手动将文件重命名为 photo.jpg,但由于真实的扩展名被隐藏,该文件在磁盘上的真实全称实际上变成了 photo.jpg.jpg 或 photo.jpg.png。
dir(Windows)或 ls -l(macOS/Linux),查看文件的真实完整后缀。
步骤 3:排查大小写匹配与转义字符干扰
在 Windows 下文件系统通常对大小写不敏感,但在 Linux 和 macOS 服务器环境下,文件系统是严格区分大小写的。例如 cover.JPG 与 cover.jpg 是两个完全不同的文件。
另外,在 Windows 路径中使用反斜杠 \ 时,容易与 Python 字符串转义字符发生意外冲突:
# 错误示例:\t 会被 Python 解释为制表符 Tab,\n 会被解释为换行符
path = "C:\new_project\test_images\cat.jpg"
# 正确写法 1:字符串前加 r,声明为原始字符串 (Raw String)
path = r"C:\new_project\test_images\cat.jpg"
# 正确写法 2:统一改用斜杠 /(Python 在各平台均良好支持)
path = "C:/new_project/test_images/cat.jpg"
步骤 4:在读取前进行显式存在性验证
通过 os.path.exists() 或 pathlib.Path.is_file() 在读取前主动进行断言,若未通过则输出有明确指导意义的提示信息,避免程序直接崩溃:
from pathlib import Path
img_file = Path("cat.jpg")
if not img_file.is_file():
print(f"错误:未能定位到图片文件,请核对完整路径: {img_file.resolve()}")
else:
print("文件校验通过,准备读取。")
三、彻底解决问题的标准代码方案
为了让代码无论在 PyCharm、VS Code 还是在任何目录下的终端执行都能百分之百正常读取图片,最佳实践是摆脱对终端工作目录的依赖,使用脚本文件自身的物理位置作为基准锚点。
方案 1:现代化标准写法 —— 使用 pathlib(强烈推荐)
Python 3.4 引入的 pathlib 模块提供了面向对象的文件系统路径管理方式。它能够自动根据操作系统转换路径分隔符,也是官方推荐的标准库:
from pathlib import Path
from PIL import Image
# 1. 获取当前正在执行的代码文件所在目录的绝对路径
BASE_DIR = Path(__file__).resolve().parent
# 2. 拼接图片相对路径(支持 / 运算符)
image_path = BASE_DIR / "images" / "avatar.png"
# 3. 读取前校验并提供清晰的排查提示
if not image_path.is_file():
raise FileNotFoundError(f"未找到图片文件,预期物理路径为: {image_path}")
# 4. 正常打开图片
with Image.open(image_path) as img:
print(f"图片读取成功!尺寸为: {img.size}, 格式为: {img.format}")
方案 2:经典兼容写法 —— 使用 os.path
如果需要维护兼容早期 Python 版本的项目代码,可以使用 os.path 实现相同的逻辑:
import os
from PIL import Image
# 获取当前脚本所在目录
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
# 拼接跨平台的图片路径
image_path = os.path.join(BASE_DIR, "images", "avatar.png")
if not os.path.exists(image_path):
raise FileNotFoundError(f"文件不存在: {image_path}")
img = Image.open(image_path)
img.show()
方案 3:不同图像库在文件缺失时的表现差异
不同 Python 图像处理库在遇到文件不存在时的反应各不相同,读者需要准确识别其表现:
| 图像处理库 | 文件不存在时的行为 | 典型错误信息 | 排查与注意事项 |
|---|---|---|---|
| Pillow (PIL) | 立即抛出明确异常 | FileNotFoundError: [Errno 2] No such file or directory |
行为符合直觉,直接定位路径并修正即可。 |
| OpenCV (cv2) | 静默失败,返回 None,后续使用时才崩溃 | AttributeError: 'NoneType' object has no attribute 'shape' |
cv2.imread() 不会主动报 FileNotFoundError,必须立即校验返回值是否为 None。 |
| Matplotlib (plt) | 底层调用文件流抛错 | FileNotFoundError 或 ValueError |
通过 plt.imread() 读取时直接抛出文件不存在异常。 |
四、进阶场景与特殊避坑指南
除了常规的代码开发外,在一些特定的开发与部署环境中,处理图片路径还需要注意以下特殊情况:
1. Jupyter Notebook / 交互式环境下的处理
在 .ipynb 交互式笔记本或 Python REPL 环境中,并不存在 __file__ 这个全局变量。如果直接使用 Path(__file__),会报 NameError: name '__file__' is not defined。
此时应当使用 Path.cwd() 作为基准,并确保启动 Jupyter 的根目录与项目结构匹配:
from pathlib import Path
from PIL import Image
# 在 Jupyter Notebook 中使用当前工作目录
CURRENT_DIR = Path.cwd()
image_path = CURRENT_DIR / "images" / "test.png"
if image_path.is_file():
img = Image.open(image_path)
else:
print(f"Jupyter 当前目录为 {CURRENT_DIR},未找到目标图片。")
2. Windows 环境下 OpenCV 读取含中文路径报错
在 Windows 系统上,cv2.imread() 对包含中文字符的路径支持不佳,常常因系统编码转换失败而直接返回 None。针对中文路径,推荐使用 numpy 配合 cv2.imdecode() 进行读取:
import cv2
import numpy as np
chinese_path = "D:/项目相册/风景/黄山.jpg"
# 解决 OpenCV 无法直接读取中文路径的问题
img = cv2.imdecode(np.fromfile(chinese_path, dtype=np.uint8), cv2.IMREAD_COLOR)
if img is None:
raise FileNotFoundError(f"无法读取该文件,请检查文件是否存在或损坏: {chinese_path}")
3. PyInstaller 打包为 EXE 后的资源路径问题
当使用 PyInstaller 将 Python 项目打包成单个独立 EXE 可执行文件时,静态图片资源在运行时会被解压到操作系统的临时目录(通过 sys._MEIPASS 记录)。此时如果仍通过 __file__ 找同级目录,就会出现打包后找不到图片的现象。
import sys
from pathlib import Path
def get_resource_path(relative_path: str) -> Path:
"""获取资源绝对路径,兼顾普通开发与 PyInstaller 打包环境"""
if hasattr(sys, '_MEIPASS'):
# PyInstaller 单文件打包解压后的临时目录
base_path = Path(sys._MEIPASS)
else:
# 普通开发运行环境
base_path = Path(__file__).resolve().parent
return base_path / relative_path
五、如何确认问题已彻底解决
完成上述代码改造后,可通过以下三步验证问题的彻底解决:
- 切换终端路径测试:打开系统终端,切换到任意与当前项目无关的目录(例如用户的根主目录),然后通过完整命令调用你的脚本:
python /absolute/path/to/your_script.py。如果依然能够正常读取并处理图片,说明已经彻底摆脱了 CWD 依赖。 - 重命名与缺失测试:故意将代码中的图片文件名写错一个字母,观察程序是否能够输出清晰、包含绝对路径的自定义报错提示,而不是毫无头绪的深层崩溃调用栈。
- 跨平台测试(可选):若项目需部署到 Linux 云服务器或 Docker 容器,确保代码中的路径连接符均由
pathlib或os.path.join处理,文件名大小写与磁盘完全一致。
通过建立统一的基准锚点和标准化的路径处理习惯,FileNotFoundError 将不再成为困扰图片数据处理的拦路虎。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













