Dependencies

(As usual, when a package is listed one needs the parts used to build programs against it, called -devel on many systems. This is not special about gdal.)

• SWIG (4 or greater).

• libgdal (3.12.4 or greater).

• numpy (1.0.0 or greater). This is not force-required by the build, but many examples and utilities will not work without it. At least osgeo.gdal_array requires numpy at build time; building without numpy and installing it later does not result in correct operation. apparently not and in any case it is an unwarranted leap.

• setuptools (python)

• wheel (python)

Building when building the rest of GDAL

Python bindings are generated by default when building GDAL from source. For more detail, see Python bindings options

Building just the bindings, from the full tree

Another is to use the gdal source distribution with an already-installed gdal library and headers. To do this, one must create a build directory and run cmake to generate build scripts. Then, run cmake --build . --target python_generated_files. Finally, in swig/python, one can build using setup.py like any other distributed python module.

Building from the PyPi module file

The third is to obtain the PyPi-hosted module file, within which swig has been run; this saves running cmake and generating bindings. See HOWTO-RELEASE for how this is created. Because swig has been run, it need not be installed.

General

Many packaging systems (on GNU/Linux, various BSDs) provide the bindings as a package. Specific instruction are given in cases when that hint might not be sufficient.

pip

Due to the complex nature of GDAL and its components, different bindings may require additional packages and installation steps. GDAL can be installed from the Python Package Index:

pip install gdal

In order to enable numpy-based raster support, libgdal and its development headers must be installed as well as the Python packages numpy, setuptools, and wheel. To install the Python dependencies and build numpy-based raster support:

pip install numpy>1.0.0 wheel setuptools>=67
pip install gdal[numpy]=="$(gdal-config --version).*"

Users can verify that numpy-based raster support has been installed with:

python3 -c 'from osgeo import gdal_array'

If this command raises an ImportError, numpy-based raster support has not been properly installed:

Traceback (most recent call last):
File "<string>", line 1, in <module>
File "/usr/local/lib/python3.12/dist-packages/osgeo/gdal_array.py", line 10, in <module>
  from . import _gdal_array
ImportError: cannot import name '_gdal_array' from 'osgeo' (/usr/local/lib/python3.12/dist-packages/osgeo/__init__.py)

This is most often due to pip reusing a cached GDAL installation. Verify that the necessary dependencies have been installed and then run the following to force a clean build:

pip install --no-cache --force-reinstall gdal[numpy]=="$(gdal-config --version).*"

Potential issues with GDAL >= 3.9, Python >= 3.9 and NumPy 2.0 (pip)

The pyproject.toml file of GDAL 3.9 requires numpy >= 2.0.0rc1 (for Python >= 3.9) at build time to be able to build bindings that are compatible of both NumPy 1 and NumPy 2. If for some reason the numpy >= 2.0.0rc1 build dependency can not be installed, it is possible to manually install the build requirements, and invoke pip install with the --no-build-isolation flag.

pip install numpy==<required_version> wheel setuptools>=67
pip install gdal[numpy]=="$(gdal-config --version).*" --no-build-isolation

Conda

GDAL can be quite complex to build and install, particularly on Windows and MacOS. Pre built binaries are provided for the conda system:

https://docs.conda.io/

By the conda-forge project:

https://conda-forge.org/

Once you have Anaconda or Miniconda installed, you should be able to install GDAL with:

conda install -c conda-forge gdal

Imports

There are five major modules that are included with the GDAL Python bindings.:

>>> from osgeo import gdal
>>> from osgeo import ogr
>>> from osgeo import osr
>>> from osgeo import gdal_array
>>> from osgeo import gdalconst

API

• API documentation is available at https://gdal.org/api/python