# 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.

## 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:

  - GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …

  - OSM - OpenStreetMap XML and PBF

- 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_DATA: Common options for raster programs

- GDAL_ENABLE_TIFF_SPLIT: GTiff – GeoTIFF File Format

- GDAL_GEOREF_SOURCES: GTiff – GeoTIFF File Format

- 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:

  - gdaladdo

  - GTiff – GeoTIFF File Format

  - MVT: Mapbox Vector Tiles

  - GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …

- GDAL_PROXY_AUTH: GDAL Virtual File Systems (compressed, network hosted, etc…): /vsimem, /vsizip, /vsitar, /vsicurl, …

- 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:

  - VICAR – VICAR

  - PDS – Planetary Data System v3

- 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

- 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:

  - gdaladdo

  - GTiff – GeoTIFF File Format

- 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