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 sysconfdirfor Windows builds, the location pointed by $(USERPROFILE)/.gdal/gdalrc is attempted.
A configuration file is a text file in a .ini style format, that lists configuration options and their values. Lines starting with # are comment lines.
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.
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.
ATTRIBUTES_SKIP: GeoJSON
AWS_ACCESS_KEY_ID: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_CONFIG_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_DEFAULT_PROFILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_DEFAULT_REGION: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_HTTPS: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_NO_SIGN_REQUEST=YES: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_PROFILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_REGION: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_REQUEST_PAYER: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_S3_ENDPOINT: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_SECRET_ACCESS_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_SESSION_TOKEN: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AWS_VIRTUAL_HOSTING: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AZURE_NO_SIGN_REQUEST=YES: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AZURE_SAS: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AZURE_STORAGE_ACCESS_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AZURE_STORAGE_ACCOUNT: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
AZURE_STORAGE_CONNECTION_STRING: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
BIGTIFF_OVERVIEW: gdaladdo
COMPRESS_OVERVIEW: gdaladdo
CPL_AWS_CREDENTIALS_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_CURL_VERBOSE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_GS_CREDENTIALS_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_MACHINE_IS_GCE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_TMPDIR:
CPL_VSIL_CURL_CACHE_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_CURL_CHUNK_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_CURL_IGNORE_GLACIER_STORAGE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_CURL_NON_CACHED: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_CURL_USE_HEAD: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_CURL_USE_S3_REDIRECT: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_DEFLATE_CHUNK_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_GZIP_WRITE_PROPERTIES: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CPL_VSIS3_USE_BASE_RMDIR_RECURSIVE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
CURL_CA_BUNDLE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
DXF_3D_EXTENSIBLE_MODE: AutoCAD DXF
DXF_ENCODING: AutoCAD DXF
DXF_FEATURE_LIMIT_PER_BLOCK: AutoCAD DXF
DXF_HATCH_TOLERANCE: AutoCAD DXF
DXF_INCLUDE_RAW_CODE_VALUES: AutoCAD DXF
DXF_INLINE_BLOCKS: AutoCAD DXF
DXF_MERGE_BLOCK_GEOMETRIES: AutoCAD DXF
DXF_TRANSLATE_ESCAPE_SEQUENCES: AutoCAD DXF
DXF_WRITE_HATCH: AutoCAD DXF
ESRI_XML_PAM: GTiff – GeoTIFF File Format
GDAL_CACHEMAX: Configuration options
GDAL_DAAS_ACCESS_TOKEN: DAAS (Airbus DS Intelligence Data As A Service driver)
GDAL_DAAS_API_KEY: DAAS (Airbus DS Intelligence Data As A Service driver)
GDAL_DAAS_CLIENT_Id: DAAS (Airbus DS Intelligence Data As A Service driver)
GDAL_DAAS_X_FORWARDED_USER: DAAS (Airbus DS Intelligence Data As A Service driver)
GDAL_DATA: Common options for raster programs
GDAL_ENABLE_TIFF_SPLIT: GTiff – GeoTIFF File Format
GDAL_GEOREF_SOURCES: GTiff – GeoTIFF File Format
GDAL_HTTPS_PROXY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_HTTP_HEADER_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_HTTP_MAX_RETRY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_HTTP_PROXY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_HTTP_PROXYUSERPWD: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_HTTP_RETRY_DELAY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_INGESTED_BYTES_AT_OPEN: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_MAX_CONNECTIONS: WMS – Web Map Services
GDAL_NUM_THREADS:
GDAL_PDF_BANDS: PDF – Geospatial PDF
GDAL_PDF_DPI: PDF – Geospatial PDF
GDAL_PDF_LAUNDER_LAYER_NAMES: PDF – Geospatial PDF
GDAL_PDF_LAYERS: PDF – Geospatial PDF
GDAL_PDF_LAYERS_OFF: PDF – Geospatial PDF
GDAL_PDF_NEATLINE: PDF – Geospatial PDF
GDAL_PDF_RENDERING_OPTIONS: PDF – Geospatial PDF
GDAL_PROXY_AUTH: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GDAL_STACTA_SKIP_MISSING_METATILE: STACTA - Spatio-Temporal Asset Catalog Tiled Assets
GDAL_TIFF_INTERNAL_MASK: GTiff – GeoTIFF File Format
GDAL_TIFF_INTERNAL_MASK_TO_8BIT: GTiff – GeoTIFF File Format
GDAL_TIFF_OVR_BLOCKSIZE: GTiff – GeoTIFF File Format
GDAL_TRY_PDS3_WITH_VICAR:
GDAL_USER_PWD: PDF – Geospatial PDF
GEOMETRY_AS_COLLECTION: GeoJSON
GOOGLE_APPLICATION_CREDENTIALS: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_ACCESS_KEY_ID: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_CLIENT_EMAIL: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_CLIENT_ID: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_CLIENT_SECRET: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_PRIVATE_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_PRIVATE_KEY_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_PRIVATE_KEY_FILE): GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_REFRESH_TOKEN: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_OAUTH2_SCOPE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GS_SECRET_ACCESS_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
GTIFF_DIRECT_IO: GTiff – GeoTIFF File Format
GTIFF_IGNORE_READ_ERRORS: GTiff – GeoTIFF File Format
GTIFF_LINEAR_UNITS: GTiff – GeoTIFF File Format
GTIFF_POINT_GEO_IGNORE: GTiff – GeoTIFF File Format
GTIFF_REPORT_COMPD_CS: GTiff – GeoTIFF File Format
GTIFF_VIRTUAL_MEM_IO: GTiff – GeoTIFF File Format
GTIFF_WRITE_TOWGS84: GTiff – GeoTIFF File Format
INTERLEAVE_OVERVIEW: gdaladdo
JPEG_QUALITY_OVERVIEW: GTiff – GeoTIFF File Format
MITAB_SET_TOWGS84_ON_KNOWN_DATUM: MapInfo TAB and MIF/MID
NAME: Configuration options
OGR_ARC_MAX_GAP: AutoCAD DXF
OGR_ARC_STEPSIZE: AutoCAD DXF
OGR_EDIGEO_FONT_SIZE_FACTOR: EDIGEO
OGR_GEOJSON_ARRAY_AS_STRING: GeoJSON
OGR_GEOJSON_DATE_AS_STRING: GeoJSON
OGR_GEOJSON_MAX_OBJ_SIZE: GeoJSON
OGR_ORGANIZE_POLYGONS: ESRI Shapefile / DBF
OGR_PDF_READ_NON_STRUCTURED: PDF – Geospatial PDF
OGR_PG_RETRIEVE_FID: PostgreSQL / PostGIS - Advanced Driver Information
OGR_SQL_LIKE_AS_ILIKE: OGR SQL dialect
OSM_COMPRESS_NODES: OSM - OpenStreetMap XML and PBF
OSM_CONFIG_FILE: OSM - OpenStreetMap XML and PBF
OSM_MAX_TMPFILE_SIZE: OSM - OpenStreetMap XML and PBF
OSM_USE_CUSTOM_INDEXING: OSM - OpenStreetMap XML and PBF
OSS_ACCESS_KEY_ID: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
OSS_ENDPOINT: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
OSS_SECRET_ACCESS_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
PHOTOMETRIC_OVERVIEW: gdaladdo
SHAPE_2GB_LIMIT: ESRI Shapefile / DBF
SHAPE_ENCODING: ESRI Shapefile / DBF
SHAPE_RESTORE_SHX: ESRI Shapefile / DBF
SHAPE_REWIND_ON_WRITE: ESRI Shapefile / DBF
SSL_CERT_FILE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
SWIFT_AUTH_TOKEN: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
SWIFT_AUTH_V1_URL: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
SWIFT_KEY: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
SWIFT_STORAGE_URL: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
SWIFT_USER: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
TAB_APPROX_GEOTRANSFORM: GTiff – GeoTIFF File Format
TIFF_USE_OVR: GTiff – GeoTIFF File Format
USE_RRD:
VRT_VIRTUAL_OVERVIEWS: VRT – GDAL Virtual Format
VSIOSS_CHUNK_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
VSIS3_CHUNK_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
VSI_CACHE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
VSI_CACHE_SIZE: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBHDFS_DATANODE_HOST: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBHDFS_DELEGATION: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBHDFS_PERMISSION: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBHDFS_REPLICATION: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBHDFS_USERNAME: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …
WEBP_LEVEL_OVERVIEW: GTiff – GeoTIFF File Format