Introduction

UnidentifiedImageError in Pillow means the library could not parse the input as a supported image. The cause is usually not mysterious: the file path is wrong, the bytes are not actually an image, the download is incomplete, or the image format is unsupported in the current Pillow build.

Start with the Simplest Checks

Verify that the path points to a real file and that the file is not empty.

1from pathlib import Path
2from PIL import Image, UnidentifiedImageError
3
4path = Path('example.png')
5print(path.exists(), path.stat().st_size if path.exists() else 'missing')
6
7try:
8    with Image.open(path) as img:
9        print(img.format, img.size)
10except UnidentifiedImageError:
11    print('Pillow could not identify the image file.')

A missing file often raises FileNotFoundError, but a zero-byte or corrupted file can easily reach Pillow and then trigger UnidentifiedImageError.

Confirm the Bytes Match the Extension

A file named .png is not necessarily a real PNG. The extension may be wrong, or the file may actually contain HTML from a failed download, an API error response, or some other non-image content.

1from pathlib import Path
2
3path = Path('example.png')
4print(path.read_bytes()[:20])

If the file starts with HTML-like bytes or plain text rather than an image signature, Pillow is doing the right thing by rejecting it.

Use verify() for Validation

If you only want to validate that the file looks like an image, verify() is useful.

1from PIL import Image, UnidentifiedImageError
2
3try:
4    with Image.open('example.png') as img:
5        img.verify()
6    print('Image structure looks valid')
7except UnidentifiedImageError:
8    print('Not an identifiable image')
9except Exception as exc:
10    print('Image exists but failed validation:', exc)

After verify(), reopen the image if you want to process pixel data. Verification is a check, not a full reusable load.

Handle BytesIO Carefully

This error also appears when loading images from memory buffers. The most common mistakes are passing incomplete bytes or forgetting to rewind the stream.

1from io import BytesIO
2from PIL import Image
3
4raw_bytes = open('example.png', 'rb').read()
5buffer = BytesIO(raw_bytes)
6
7with Image.open(buffer) as img:
8    print(img.size)

If a previous operation already consumed the stream, call buffer.seek(0) before opening it with Pillow.

Unsupported Formats and Environment Issues

Pillow supports many formats, but not every build supports every codec equally. If a file is valid but still cannot be identified, check whether the environment has the necessary support for that format and whether the Pillow version is current enough for the file type you are using.

This matters especially for less common formats, newer encodings, and minimal container environments.

Network Downloads Need Extra Suspicion

This error appears frequently after downloading files from URLs. The saved file may have the right extension but contain an HTTP error page, redirect body, or authentication response instead of image bytes. Checking the response status code and content type before saving the file avoids a surprising number of image-opening failures.

Common Pitfalls

• Assuming the filename extension proves the file is a real image.
• Ignoring the possibility that a failed HTTP request saved HTML or JSON instead of image bytes.
• Using a BytesIO stream without rewinding it before Image.open.
• Treating verify() as though it keeps the image object ready for normal processing.
• Blaming Pillow immediately instead of checking whether the input file is empty, truncated, or corrupted.

Summary

• 'UnidentifiedImageError usually means the bytes are not a valid recognizable image for Pillow.'
• Start with path existence, file size, and a quick look at the first bytes.
• Use verify() to validate image structure when needed.
• Rewind in-memory streams before opening them.
• The problem is often the input data, not the image library itself.