{"id":7560,"library":"pygdal","title":"pygdal","description":"pygdal provides virtualenv and setuptools friendly Python bindings for the GDAL (Geospatial Data Abstraction Library) C API. It was created to address installation difficulties with the standard GDAL Python bindings for GDAL versions prior to 3.7. The project maintains a 3.6.* release line as the last for GDAL versions before 3.7, after which GDAL can be installed directly from PyPI. It focuses on offering a more 'pythonic' interface and integrates with NumPy for data handling.","status":"maintenance","version":"3.6.4.11","language":"en","source_language":"en","source_url":"https://github.com/nextgis/pygdal","tags":["geospatial","GIS","GDAL","OGR","raster","vector"],"install":[{"cmd":"pip install pygdal==\"$(gdal-config --version).*\"","lang":"bash","label":"Recommended specific version install"},{"cmd":"pip install pygdal","lang":"bash","label":"General install (may require specific version pinning)"},{"cmd":"sudo apt-get install libgdal-dev","lang":"bash","label":"System dependency (Ubuntu/Debian)"}],"dependencies":[{"reason":"Used for reading and writing data, listed as a dependency.","package":"numpy","optional":false},{"reason":"pygdal provides Python bindings but requires the underlying GDAL C library and its development headers to be installed on the system.","package":"GDAL C library and headers","optional":false}],"imports":[{"note":"The official Python bindings, including those provided by pygdal, expose GDAL functionality via the `osgeo` package, not directly as `gdal`.","wrong":"import gdal","symbol":"gdal","correct":"from osgeo import gdal"},{"note":"OGR is the vector data library component of GDAL, accessed via `osgeo`.","symbol":"ogr","correct":"from osgeo import ogr"},{"note":"OSR handles spatial reference systems and is accessed via `osgeo`.","symbol":"osr","correct":"from osgeo import osr"}],"quickstart":{"code":"from osgeo import gdal\nimport os\n\ndef open_gdal_dataset(filepath):\n    \"\"\"Opens a GDAL dataset and prints some basic information.\"\"\"\n    if not os.path.exists(filepath):\n        print(f\"Error: File not found at {filepath}\")\n        return\n\n    # Enable GDAL exceptions for clearer error handling\n    gdal.UseExceptions()\n    try:\n        dataset = gdal.Open(filepath, gdal.GA_ReadOnly)\n        if dataset is None:\n            print(f\"Could not open {filepath}\")\n            return\n\n        print(f\"Successfully opened: {filepath}\")\n        print(f\"Driver: {dataset.GetDriver().LongName} ({dataset.GetDriver().ShortName})\")\n        print(f\"Size: {dataset.RasterXSize}x{dataset.RasterYSize}x{dataset.RasterCount}\")\n        print(f\"Projection: {dataset.GetProjection()[:50]}...\") # Print first 50 chars\n        print(f\"GeoTransform: {dataset.GetGeoTransform()}\")\n        # Close the dataset implicitly when `dataset` goes out of scope, or explicitly with dataset=None\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\n# Example usage (requires a dummy GeoTIFF file, or replace with an existing file path)\n# Create a dummy file for demonstration if it doesn't exist\ndummy_tif = \"dummy.tif\"\nif not os.path.exists(dummy_tif):\n    driver = gdal.GetDriverByName(\"GTiff\")\n    rows, cols = 100, 100\n    dataset = driver.Create(dummy_tif, cols, rows, 1, gdal.GDT_Byte)\n    dataset.SetGeoTransform((0, 1, 0, 0, 0, -1))\n    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\"]]')\n    band = dataset.GetRasterBand(1)\n    band.WriteArray([[i % 255 for i in range(cols)] for _ in range(rows)])\n    dataset = None # Close the dataset\n\nopen_gdal_dataset(dummy_tif)\n# Clean up dummy file\nos.remove(dummy_tif)\n","lang":"python","description":"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."},"warnings":[{"fix":"For 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).*\"`).","message":"pygdal 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.","severity":"breaking","affected_versions":"<3.7"},{"fix":"Call `gdal.UseExceptions()` at the beginning of your script to enable Python exceptions for GDAL errors.","message":"GDAL 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Using 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.","severity":"gotcha","affected_versions":"All versions, especially <3.7"},{"fix":"Always try to install `pygdal` with a version specifier that matches your `gdal-config --version` output, for example: `pip install pygdal==\"$(gdal-config --version).*\"`.","message":"A 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Try downgrading `pip` and `setuptools` (e.g., `pip install pip==23.3.2 setuptools==65.5.1`) or ensure you have all necessary build tools and GDAL development headers installed on your system.","cause":"This error often indicates issues with the build environment, potentially related to newer `pip` or `setuptools` versions and how they handle project metadata generation.","error":"error: subprocess-exited-with-error × Preparing metadata (pyproject.toml) did not run successfully."},{"fix":"Upgrade `pygdal` to the latest 3.6.* version. If the problem persists, try downgrading `setuptools` (e.g., `pip install setuptools==58.0.2`).","cause":"This error appears in older versions of `pygdal` when used with newer `setuptools` versions, as `use_2to3` was a Python 2 to 3 migration tool option that became invalid.","error":"error in pygdal setup command: use_2to3 is invalid."},{"fix":"Verify that your Python architecture (32-bit vs. 64-bit) matches your GDAL installation. Ensure the GDAL C library is correctly installed and its `bin` and `lib` directories are in your system's `PATH` environment variable. For Windows, check `GDAL_DATA` and `GDAL_DRIVER_PATH` environment variables.","cause":"This typically means that the Python bindings cannot find or load the underlying GDAL C library. Common causes include 32-bit Python trying to load 64-bit GDAL (or vice-versa), incorrect `PATH` environment variable, or missing GDAL system installations.","error":"ImportError: DLL load failed: The operating system cannot run %1. (or similar DLL/shared library load error on Windows) / ImportError: No module named _gdal (on Linux/macOS)"}]}