RasterioIOError: Not Recognized as a Supported File Format (How to Fix) #

Problem statement #

A common Rasterio problem is that rasterio.open() fails with an error like one of these:

rasterio.errors.RasterioIOError: 'data/dem.tif' not recognized as being in a supported file format

or:

rasterio.errors.RasterioIOError: data/dem.tif: No such file or directory

This usually appears on the first line of a workflow, before you read any pixel values. In practice, it shows up as one of these cases:

• the path looks correct, but Python cannot find the file
• the file exists, but Rasterio refuses to open it
• the same file opens in QGIS but fails in Python
• a download finished, but the file will not open

If you are trying to fix this error, the cause is usually one of these issues:

• a wrong or relative path, so the file is not found
• the file is actually a different format than its extension suggests
• a corrupted or partial download
• missing sidecar files that the format depends on
• an unextracted container such as a .zip or .tif.gz
• a GDAL driver that is not available in your environment

The goal is to identify which category the problem belongs to and apply the right fix quickly.

Quick answer #

Most RasterioIOError failures are fixed by checking the path first, then opening the raster inside a context manager.

1. Confirm the path exists with pathlib before opening.
2. Use an absolute path and print it to remove any doubt.
3. Check the real file type, not just the extension.
4. Extract archives such as .zip or .tif.gz before opening.
5. Confirm the GDAL driver for the format is available.
6. Re-download the file if it is corrupted or incomplete.

import rasterio
from pathlib import Path

raster_path = Path("data/dem.tif").resolve()
print("Opening:", raster_path)
print("Exists:", raster_path.exists())

if not raster_path.exists():
    raise FileNotFoundError(raster_path)

with rasterio.open(raster_path) as src:
    print("Driver:", src.driver)
    print("Band count:", src.count)
    band1 = src.read(1)
    print("Band 1 shape:", band1.shape)

This confirms the file is present, then opens it with Rasterio and reports the driver that GDAL used.

Diagnosis flow #

Step-by-step solution #

Verify the path exists with pathlib #

Many RasterioIOError cases are simple path problems. The "No such file or directory" variant almost always means the file is not where the code is looking.

from pathlib import Path

raster_path = Path("data/dem.tif").resolve()
print("Resolved path:", raster_path)
print("Exists:", raster_path.exists())
print("Is file:", raster_path.is_file())
print("Size:", raster_path.stat().st_size if raster_path.exists() else "missing")

Common causes:

• wrong working directory, so a relative path resolves to the wrong place
• a typo in the filename
• the file renamed or moved
• Windows backslash escaping problems

If exists() returns False, fix the path before doing anything else.

Inspect the real file type, not the extension #

A file named dem.tif is not always a GeoTIFF. Portals sometimes serve HTML error pages, ZIP archives, or JSON with the wrong extension. Reading the first bytes reveals the real type.

from pathlib import Path

raster_path = Path("data/dem.tif")
with open(raster_path, "rb") as f:
    header = f.read(8)

print("Extension:", raster_path.suffix)
print("First bytes:", header)

Some signatures to recognize:

• b"II*\x00" or b"MM\x00*" — a real TIFF/GeoTIFF
• b"PK\x03\x04" — a ZIP archive, not a raster
• b"\x1f\x8b" — a gzip archive (for example .tif.gz)
• b"<!DOCTYP" or b"<html" — an HTML page, usually a failed download

If the header does not match the format you expected, the file is the problem, not Rasterio.

List available GDAL drivers #

Rasterio reads formats through GDAL drivers. If the driver for your format is not built into your GDAL, the file will not open even when it is valid.

import rasterio

# Names of drivers GDAL can use in this environment
print(sorted(rasterio.drivers.raster_driver_extensions().values()))

with rasterio.Env() as env:
    print("GDAL drivers available:", len(env.drivers()))
    print("Has GTiff:", "GTiff" in env.drivers())

If a common driver such as GTiff is missing, the GDAL build is incomplete and the environment needs to be reinstalled, usually from conda-forge.

Handle zipped or compressed rasters #

If the file is a ZIP archive or a .tif.gz, Rasterio cannot open it as a plain raster. You have two options: extract it first, or point Rasterio at the file inside the archive using a GDAL virtual path.

Extract first:

import zipfile
import rasterio

with zipfile.ZipFile("data/dem.zip") as z:
    z.extractall("data/dem_extracted")

with rasterio.open("data/dem_extracted/dem.tif") as src:
    print("Driver:", src.driver)

Or open the raster inside the ZIP directly with the /vsizip/ virtual file system:

import rasterio

with rasterio.open("/vsizip/data/dem.zip/dem.tif") as src:
    print("Driver:", src.driver)
    print("Band count:", src.count)

The /vsizip/ prefix tells GDAL to look inside the archive without extracting it to disk.

Code examples #

Example 1: Open with error handling and report the cause #

import rasterio
from rasterio.errors import RasterioIOError
from pathlib import Path

raster_path = "data/dem.tif"

try:
    with rasterio.open(raster_path) as src:
        print("Opened:", src.driver)
        print("Size:", src.width, "x", src.height)
except RasterioIOError as e:
    print("Could not open raster:")
    print(e)
    if not Path(raster_path).exists():
        print("File does not exist at this path.")

Example 2: Open a raster inside a ZIP with a virtual path #

import rasterio

# Pattern: /vsizip/<path-to-zip>/<path-inside-zip>
vsi_path = "/vsizip/data/dem.zip/dem.tif"

with rasterio.open(vsi_path) as src:
    print("Driver:", src.driver)
    print("CRS:", src.crs)
    band1 = src.read(1)
    print("Shape:", band1.shape)

Example 3: Confirm the driver used to open a file #

import rasterio

raster_path = "data/landcover.tif"

with rasterio.open(raster_path) as src:
    print("Driver:", src.driver)      # for a GeoTIFF this prints "GTiff"
    print("Profile:")
    print(src.profile)

If src.driver is not what you expect, GDAL identified the file as a different format than you intended.

Example 4: Check whether a format's driver is available before opening #

import rasterio

required_driver = "GTiff"

with rasterio.Env() as env:
    available = env.drivers()

if required_driver in available:
    with rasterio.open("data/dem.tif") as src:
        print("Opened with:", src.driver)
else:
    print(f"{required_driver} driver is not available in this GDAL build.")

Explanation #

Rasterio does not parse raster files itself. It hands the path to GDAL, which tries each registered driver in turn until one recognizes the data. The driver is chosen by content, not only by extension. When no driver claims the file, GDAL reports that it is "not recognized as being in a supported file format," and Rasterio raises RasterioIOError.

This means the error has two broad causes. Either GDAL never received valid bytes, or it received bytes that no available driver understands.

The first cause covers missing files, wrong paths, partial downloads, and unextracted archives. In those cases the file is absent, truncated, or is really a container such as a ZIP. The "No such file or directory" message is the clearest sign of this group.

The second cause covers genuine format and driver problems. The file might be a format whose driver is not in your GDAL build, or it might be corrupted so that no driver matches its header. Checking src.driver on files that do open, and listing the drivers in your environment, helps separate these cases.

Because format detection is content-based, the file extension is only a hint. A correct extension on a corrupted or mislabeled file will still fail, which is why inspecting the first bytes is a reliable diagnostic.

Edge cases or notes #

Relative vs absolute paths #

A relative path like data/dem.tif depends on the current working directory, which can differ between your editor, a notebook, and a scheduled job. Resolve to an absolute path with Path(...).resolve() and print it before opening.

Partial or corrupted downloads #

A download that stops early often leaves a file with the right name and extension but truncated content. The size will be smaller than expected, and the header bytes may be wrong. Re-download the file and compare its size against the source.

.tif vs .tiff #

Both extensions map to the same GeoTIFF driver in GDAL, so the difference does not cause this error by itself. If only one opens, the failing file is usually the corrupted or mislabeled one, not a victim of the extension.

Network and URL rasters #

GDAL can read remote rasters over HTTP using the /vsicurl/ prefix, for example /vsicurl/https://example.com/dem.tif. These fail if the URL is wrong, the server returns an error page, or the build lacks the curl virtual file system. Test the URL in a browser first.

Windows path separators #

On Windows, backslashes in normal strings are escape characters, so "C:\new\dem.tif" can break. Use a raw string r"C:\data\dem.tif", forward slashes, or a pathlib.Path. Note that GDAL virtual paths like /vsizip/ always use forward slashes regardless of platform.

Internal links #

• Introduction to Rasterio: Reading Raster Data in Python
• How to Extract Raster Values at Point Locations with Rasterio
• How to Convert a Raster to a Vector in Python
• Vector vs Raster Data in Python GIS: Key Differences
• GeoPandas Not Reading Shapefile: Common Causes and Fixes

FAQ #

Why does Rasterio say my file is not a supported format when it opens in QGIS? #

QGIS and Rasterio both use GDAL, so this usually points to a different path, a partial copy, or a GDAL build that lacks the driver. Confirm the path exists, check the file size against the source, and list your available drivers.

How do I open a GeoTIFF that is inside a ZIP without extracting it? #

Use a GDAL virtual path with the /vsizip/ prefix, such as rasterio.open("/vsizip/data/dem.zip/dem.tif"). This reads the raster directly from the archive.

Does the file extension determine how Rasterio reads a raster? #

No. GDAL identifies the format from the file's content, trying each driver until one matches. The extension is only a hint, so a mislabeled or corrupted file still fails.

What does "No such file or directory" mean if the file is right there? #

It almost always means the path your code uses does not point to the file, often because of a relative path or wrong working directory. Print Path(raster_path).resolve() and check exists() to confirm.

How do I read a Cloud-Optimized GeoTIFF directly from a URL with Rasterio? #

Prefix the HTTPS address with /vsicurl/, for example rasterio.open("/vsicurl/https://example.com/dem.tif"). The COG format lets GDAL fetch only the needed byte ranges, but the request fails if the URL is wrong or the server returns an error page.

Why does rasterio.open() fail on a NetCDF or HDF5 file with multiple subdatasets? #

Such files expose their data through subdatasets rather than at the top level, so opening the container directly often fails or returns no bands. List src.subdatasets (or use the NETCDF:"file.nc":varname path syntax) and open the specific subdataset you need.

How do I check whether my file is truly a valid GeoTIFF before opening it? #

Read the first bytes and confirm the TIFF signature: b"II*\x00" (little-endian) or b"MM\x00*" (big-endian). If you instead see b"PK\x03\x04" it is a ZIP, and b"<!DOCTYP" means an HTML error page was downloaded in place of the raster.

Why does a JPEG or PNG open in an image viewer but fail in Rasterio? #

Plain JPEG and PNG need the matching GDAL drivers, and a build missing them will refuse the file even though it is valid. List the available drivers with rasterio.Env().drivers(); if the driver is absent, reinstall GDAL from conda-forge, which ships a fuller driver set.