How to use "gdal" CLI algorithms from Python

Principles

"gdal" CLI algorithms are available as osgeo.gdal.Algorithm instances.

A convenient way to access an algorithm and run it is to use the osgeo.gdal.Run() function.

Run(*alg, arguments={}, progress=None, **kwargs)

Run a GDAL algorithm and return it.

Added in version 3.11.

Parameters:

alg (str, list[str], tuple[str], Algorithm) -- Path to the algorithm or algorithm instance itself. For example "raster info", or ["raster", "info"] or "raster", "info".
arguments (dict) -- Input arguments of the algorithm. For example {"format": "json", "input": "byte.tif"}
progress (callable) -- Progress function whose arguments are a progress ratio, a string and a user data
kwargs -- Instead of using the arguments parameter, it is possible to pass algorithm arguments directly as named parameters of gdal.Run(). If the named argument has dash characters in it, the corresponding parameter must replace them with an underscore character. For example dst_crs as a a parameter of gdal.Run(), instead of dst-crs which is the name to use on the command line.

Return type:

a osgeo.gdal.Algorithm instance

If you do not need to access output value(s) of the algorithm, you can call Run directly: gdal.Run(["raster", "convert"], input="in.tif", output="out.tif")

The name of algorithm arguments are the long names as documented in the documentation page of each algorithm. They can also be obtained with osgeo.gdal.Algorithm.GetArgNames().

>>> gdal.Algorithm("raster", "convert").GetArgNames()
['help', 'help-doc', 'version', 'json-usage', 'drivers', 'config', 'progress', 'output-format', 'open-option', 'input-format', 'input', 'output', 'creation-option', 'overwrite', 'append']

For a command such as gdal raster info that returns a JSON output, you can get the return value of osgeo.gdal.Run() and call the osgeo.gdal.Algorithm.Output() method.

alg = gdal.Run("raster", "info", input="byte.tif")
info_as_dict = alg.Output()

If the return value is a dataset, osgeo.gdal.Run() can be used within a context manager, in which case osgeo.gdal.Algorithm.Finalize() will be called at the exit of the context manager.

with gdal.Run("raster reproject", input=src_ds, output_format="MEM",
              dst_crs="EPSG:4326") as alg:
    values = alg.Output().ReadAsArray()

When not using a context manager, osgeo.gdal.Algorithm.Finalize() can be called directly to release the algorithm's references to the output dataset and free associated resources. If a variable still references the dataset, it will not be closed and may still be accessed:

>>> alg = gdal.Run("raster reproject", input=src_ds, output_format="MEM",
               dst_crs="EPSG:4326")
>>> out_ds = alg.Output()
>>> print(out_ds.GetRefCount())
2
>>> alg.Finalize()
>>> print(out_ds.GetRefCount())
1
>>> alg.Output().ReadAsArray() # no longer available from the algorithm
AttributeError: 'NoneType' object has no attribute 'ReadAsMaskedArray'
>>> out_ds.ReadAsArray() # still accessible via the existing reference
array([[-9999., -9999., -9999., ...,

`gdal.alg` module

Added in version 3.12.

The gdal.alg module is also available with submodules and functions reflecting the hierarchy of algorithms. Functions return an osgeo.gdal.Algorithm instance similarly to osgeo.gdal.Run()

The above example running "gdal raster convert" can also be rewritten as:

>>> from osgeo import gdal
>>> gdal.alg.raster.convert(input="in.tif", output="out.tif")

The documentation of the function lists argument names, types and semantics:

>>> from osgeo import gdal
>>> help(gdal.alg.raster.convert)

    Help on function convert:

    convert(input: Union[List[osgeo.gdal.Dataset], List[str], List[os.PathLike[str]]], output: Union[osgeo.gdal.Dataset, str, os.PathLike[str]], input_format: Union[List[str], str, NoneType] = None, open_option: Union[List[str], str, NoneType] = None, output_format: Optional[str] = None, creation_option: Union[List[str], str, NoneType] = None, overwrite: Optional[bool] = None, append: Optional[bool] = None)
        Convert a raster dataset.

        Consult https://gdal.org/programs/gdal_raster_convert.html for more details.

        Parameters
        ----------
        input: Union[List[gdal.Dataset], List[str], List[os.PathLike[str]]]
            Input raster datasets
        output: Union[gdal.Dataset, str, os.PathLike[str]]
            Output raster dataset
        input_format: Optional[Union[List[str], str]]=None
            Input formats
        open_option: Optional[Union[List[str], dict, str]]=None
            Open options
        output_format: Optional[str]=None
            Output format ("GDALG" allowed)
        creation_option: Optional[Union[List[str], dict, str]]=None
            Creation option
        overwrite: Optional[bool]=None
            Whether overwriting existing output is allowed
        append: Optional[bool]=None
            Append as a subdataset to existing output


        Output parameters
        -----------------
        output: gdal.ArgDatasetValue
            Output raster dataset

Raster commands examples

Example 1: Getting information on a raster dataset as JSON

from osgeo import gdal

gdal.UseExceptions()
info_as_dict = gdal.alg.raster.info(input="byte.tif").Output()

Example 2: Converting a georeferenced netCDF file to cloud-optimized GeoTIFF

from osgeo import gdal

gdal.UseExceptions()
gdal.alg.raster.convert(input="in.tif", output="out.tif", output_format="COG", overwrite=True)

or

from osgeo import gdal

gdal.UseExceptions()
gdal.Run("raster", "convert", input="in.tif", output="out.tif",
         output_format="COG", overwrite=True)

or

from osgeo import gdal

gdal.UseExceptions()
gdal.Run(["raster", "convert"], {"input": "in.tif", "output": "out.tif", "output-format": "COG", "overwrite": True})

Example 3: Reprojecting a GeoTIFF file to a Deflate-compressed tiled GeoTIFF file

from osgeo import gdal

gdal.UseExceptions()
gdal.alg.raster.reproject(
          input="in.tif", output="out.tif",
          dst_crs="EPSG:4326",
          creation_options={ "TILED": "YES", "COMPRESS": "DEFLATE"})

Example 4: Reprojecting a (possibly in-memory) dataset to a in-memory dataset

from osgeo import gdal

gdal.UseExceptions()
with gdal.alg.raster.reproject(input=src_ds, output_format="MEM",
              dst_crs="EPSG:4326") as alg:
    values = alg.Output().ReadAsArray()

Vector commands examples

Example 5: Getting information on a vector dataset as JSON

from osgeo import gdal

gdal.UseExceptions()
info_as_dict = gdal.alg.vector.info(input="poly.gpkg").Output()

Example 6: Converting a shapefile to a GeoPackage

from osgeo import gdal

gdal.UseExceptions()
gdal.alg.vector.convert(input="in.shp", output="out.gpkg", overwrite=True)

Pipeline examples

Example 7: Perform raster reprojection and gets the result as a streamed dataset.

from osgeo import gdal

gdal.UseExceptions()
with gdal.alg.pipeline(pipeline="read byte.tif ! reproject --dst-crs EPSG:4326 --resampling cubic") as alg:
    ds = alg.Output()
    # do something with the dataset