Configuration Options

This page discussed runtime configuration options for GDAL, and is distinct from options to the build-time configure script. Runtime configuration options apply on all platforms, and are evaluated at runtime. They can be set programmatically, by commandline switches or in the environment by the user.

ConfigOptions are normally used to alter the default behavior of GDAL and OGR drivers and in some cases the GDAL and OGR core. They are essentially global variables the user can set.

Setting ConfigOptions

One example of a config option is the GDAL_CACHEMAX option. It controls the size of the GDAL block cache, in megabytes. It can be set in the environment on unix (bash/bourne) shell like this:

export GDAL_CACHEMAX=64

In a DOS/Windows command shell it is done like this:

set GDAL_CACHEMAX=64

It can also be set on the commandline for most GDAL and OGR utilities with the --config switch, though in a few cases these switches are not evaluated in time to affect behavior.

gdal_translate --config GDAL_CACHEMAX 64 in.tif out.tif

In C/C++ configuration switches can be set programmatically like this:

#include "cpl_conv.h"
...
    GDALSetConfigOption( "GDAL_CACHEMAX", "64" );

Normally a configuration option applies to all threads active in a program, but they can be limited to only the current thread this way:

    GDALSetThreadLocalConfigOption( "GDAL_CACHEMAX", "64" );

What Configuration Options Exist?

Traditionally there hasn't been a good registry of configuration options, and they are often added adhoc to drivers to provide particular workarounds. Below are some of the software wide configuration options. In some cases particular format drivers will document their configuration options, if any, in the user documentation - as is done for the ​JP2KAK driver.

Generic Options

CPL_DEBUG

This may be set to ON, OFF or specific prefixes. If it is ON, all debug messages are reported to stdout. If it is OFF or unset no debug messages are reported. If it is set to a particular value, then only debug messages with that "type" value will be reported. For instance debug messages from the HFA driver are normally reported with type "HFA" (seen in the message).

At the commandline this can also be set with --debug <value> as well as with --config CPL_DEBUG <value>.

CPL_LOG

CPL_LOG_ERRORS

CPL_TIMESTAMP

CPL_MAX_ERROR_REPORTS

CPL_ACCUM_ERROR_MSG

CPL_TMPDIR

GDAL_DATA

GEOTIFF_CSV

GDAL Options

GDAL_CACHEMAX

This option controls the default GDAL raster block cache size. If it's value is small (less than 10000 in 1.7 and earlier, 100000 in 1.8 and later) it is assumed to be measured in megabytes, otherwise in bytes. Note that this value is only consulted the first time the cache size is requested overriding the initial default (40MB in GDAL 1.7, but often changing for each release). To change this value programmatically during operation of the pgoram it is better to use GDALSetCacheMax(int nNewSize) (always in bytes).

GDAL_SKIP

GDAL_DRIVER_PATH

GDAL_FORCE_CACHING

GDAL_VALIDATE_CREATION_OPTIONS

GDAL_IGNORE_AXIS_ORIENTATION

GMLJP2OVERRIDE

GDAL_PAM_MODE

GDAL_PAM_PROXY_DIR

GDAL_MAX_DATASET_POOL_SIZE

GDAL_SWATH_SIZE

OGR Options

PROJSO

The name of the PROJ.4 DLL or shared library to try and load at runtime.

CENTER_LONG

CHECK_WITH_INVERT_PROJ

THRESHOLD

OGR_DEBUG_ORGANIZE_POLYGONS

OGR_ARC_STEPSIZE

OGR_FORCE_ASCII