Configuration options

This page discusses runtime configuration options for GDAL. These are 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.

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

How to set configuration options?

One example of a configuration 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

Or just for this command, like this:

GDAL_CACHEMAX=64 gdal_translate 64 in.tif out.tif

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 with CPLSetConfigOption():

#include "cpl_conv.h"
...
    CPLSetConfigOption( "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 with CPLSetThreadLocalConfigOption()

CPLSetThreadLocalConfigOption( "GTIFF_DIRECT_IO", "YES" );

For boolean options, the values YES, TRUE or ON can be used to turn the option on; NO, FALSE or OFF to turn it off.

GDAL configuration file

New in version 3.3.

On driver registration, loading of configuration is attempted from a set of predefined files.

The following locations are tried by CPLLoadConfigOptionsFromPredefinedFiles():

  • the location pointed by the environment variable (or configuration option) GDAL_CONFIG_FILE is attempted first. If it set, the next steps are not attempted

  • for Unix builds, the location pointed by ${sysconfdir}/gdal/gdalrc is first attempted (where ${sysconfdir} evaluates to ${prefix}/etc, unless the --sysconfdir switch of ./configure has been invoked). Then $(HOME)/.gdal/gdalrc is tried, potentially overriding what was loaded with the sysconfdir

  • for Windows builds, the location pointed by $(USERPROFILE)/.gdal/gdalrc is attempted.

A configuration file is a text file in a .ini style format. Lines starting with # are comment lines.

The file may contain a [configoptions] section, that lists configuration options and their values.

Example:

[configoptions]
# set BAR as the value of configuration option FOO
FOO=BAR

Configuration options set in the configuration file can later be overridden by calls to CPLSetConfigOption() or CPLSetThreadLocalConfigOption(), or through the --config command line switch.

The value of environment variables set before GDAL starts will be used instead of the value set in the configuration files, unless, starting with GDAL 3.6, the configuration file starts with a [directives] section that contains a ignore-env-variables=yes entry.

[directives]
# ignore environment variables. Take only into account the content of the
# [configoptions] section, or ones defined programmatically with
# CPLSetConfigOption / CPLSetThreadLocalConfigOption.
ignore-env-variables=yes

Starting with GDAL 3.5, a configuration file can also contain credentials (or more generally options related to a virtual file system) for a given path prefix, that can also be set with VSISetPathSpecificOption(). Credentials should be put under a [credentials] section, and for each path prefix, under a relative subsection whose name starts with “[.” (e.g. “[.some_arbitrary_name]”), and whose first key is “path”.

Example:

[credentials]

[.private_bucket]
path=/vsis3/my_private_bucket
AWS_SECRET_ACCESS_KEY=...
AWS_ACCESS_KEY_ID=...

[.sentinel_s2_l1c]
path=/vsis3/sentinel-s2-l1c
AWS_REQUEST_PAYER=requester
\endverbatim

List of configuration options and where they apply

Note

This list is known to be incomplete. It depends on proper annotation of configuration options where they are mentioned elsewhere in the documentation. If you want to help to extend it, use the :decl_configoption:`NAME` syntax in places where a configuration option is mentioned.