Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gdal
✓ from osgeo import gdal
✗ import gdal
The official Python bindings, including those provided by pygdal, expose GDAL functionality via the `osgeo` package, not directly as `gdal`.
ogr
✓ from osgeo import ogr
OGR is the vector data library component of GDAL, accessed via `osgeo`.
osr
✓ from osgeo import osr
OSR handles spatial reference systems and is accessed via `osgeo`.
This quickstart demonstrates how to open a geospatial raster file (GeoTIFF) using `pygdal` and retrieve basic metadata. It also shows how to explicitly enable GDAL exceptions for better error handling, which is often recommended as GDAL bindings typically return `None` on error by default.
from osgeo import gdal
import os
def open_gdal_dataset(filepath):
"""Opens a GDAL dataset and prints some basic information."""
if not os.path.exists(filepath):
print(f"Error: File not found at {filepath}")
return
# Enable GDAL exceptions for clearer error handling
gdal.UseExceptions()
try:
dataset = gdal.Open(filepath, gdal.GA_ReadOnly)
if dataset is None:
print(f"Could not open {filepath}")
return
print(f"Successfully opened: {filepath}")
print(f"Driver: {dataset.GetDriver().LongName} ({dataset.GetDriver().ShortName})")
print(f"Size: {dataset.RasterXSize}x{dataset.RasterYSize}x{dataset.RasterCount}")
print(f"Projection: {dataset.GetProjection()[:50]}...") # Print first 50 chars
print(f"GeoTransform: {dataset.GetGeoTransform()}")
# Close the dataset implicitly when `dataset` goes out of scope, or explicitly with dataset=None
except Exception as e:
print(f"An error occurred: {e}")
# Example usage (requires a dummy GeoTIFF file, or replace with an existing file path)
# Create a dummy file for demonstration if it doesn't exist
dummy_tif = "dummy.tif"
if not os.path.exists(dummy_tif):
driver = gdal.GetDriverByName("GTiff")
rows, cols = 100, 100
dataset = driver.Create(dummy_tif, cols, rows, 1, gdal.GDT_Byte)
dataset.SetGeoTransform((0, 1, 0, 0, 0, -1))
dataset.SetProjection('GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]]')
band = dataset.GetRasterBand(1)
band.WriteArray([[i % 255 for i in range(cols)] for _ in range(rows)])
dataset = None # Close the dataset
open_gdal_dataset(dummy_tif)
# Clean up dummy file
os.remove(dummy_tif)
Debug
Known issues
breakingpygdal is for GDAL versions older than 3.7. For GDAL 3.7 and later, you should install the official `GDAL` package directly from PyPI. pygdal 3.6.* is the last release of this package.fixFor GDAL >= 3.7, use `pip install GDAL`. For GDAL < 3.7, ensure your `pygdal` version matches your system's GDAL library version (e.g., `pip install pygdal=="$(gdal-config --version).*"`).
affects: <3.7
gotchaGDAL Python bindings do not raise exceptions by default when errors occur. Instead, they return an error value (like `None`) and print a message to `sys.stdout`.fixCall `gdal.UseExceptions()` at the beginning of your script to enable Python exceptions for GDAL errors.
affects: All versions
gotchaUsing a GDAL object (e.g., a raster band) after its parent object (e.g., the dataset it belongs to) has been implicitly or explicitly deleted can lead to crashes. This is particularly noted for GDAL 3.7 and earlier.fixEnsure that parent GDAL objects (like `Dataset` objects) remain in scope for as long as any child objects (like `Band` or `Layer` objects) are being used. Assign `None` to variables holding GDAL objects when you are completely finished with them to explicitly release resources.
affects: All versions, especially <3.7
gotchaA version mismatch between the `pygdal` package and the system-installed GDAL C library (e.g., `libgdal-dev` on Linux) is a common cause of installation and runtime issues.fixAlways try to install `pygdal` with a version specifier that matches your `gdal-config --version` output, for example: `pip install pygdal=="$(gdal-config --version).*"`.
affects: All versions
Upgrade
Version history
3.6.4.11latest on PyPI · released May 18, 2023
Audit
Dependencies
numpyrequiredUsed for reading and writing data, listed as a dependency.
GDAL C library and headersrequiredpygdal provides Python bindings but requires the underlying GDAL C library and its development headers to be installed on the system.