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
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
Since GDAL 3.9, it is also possible to set a config option in a more conventional
way by using a single <NAME>``=``<VALUE>
command line string instead of having <NAME>
and <VALUE>
as two space-separated strings.
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
Added 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 is set, the next steps are not attemptedfor 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. 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
Global configuration options
Logging
CPL_CURL_VERBOSE=[YES/NO]: Set to "YES" to get the curl library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding.
CPL_DEBUG=[ON/OFF/<PREFIX>]: 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=<path>: This is used for setting the log file path.
CPL_LOG_ERRORS=[ON/OFF]: Set to "ON" for printing error messages. Use together with "CPL_LOG" for directing them into a file.
CPL_TIMESTAMP=[ON/OFF]: Set to "ON" to add timestamps to CPL debug messages (so assumes that
CPL_DEBUG
is enabled)CPL_MAX_ERROR_REPORTS=value:
CPL_ACCUM_ERROR_MSG=value:
Performance and caching
GDAL_NUM_THREADS=[ALL_CPUS/<integer>]: Sets the number of worker threads to be used by GDAL operations that support multithreading. The default value depends on the context in which it is used.
GDAL_CACHEMAX=<size>: Defaults to
5%
. Controls the default GDAL raster block cache size. When blocks are read from disk, or written to disk, they are cached in a global block cache by theGDALRasterBlock
class. Once this cache exceedsGDAL_CACHEMAX
old blocks are flushed from the cache. This cache is mostly beneficial when needing to read or write blocks several times. This could occur, for instance, in a scanline oriented input file which is processed in multiple rectangular chunks by gdalwarp. If its value is small (less than 100000), it is assumed to be measured in megabytes, otherwise in bytes. Alternatively, the value can be set to "X%" to mean X% of the usable physical RAM. Note that this value is only consulted the first time the cache size is requested. To change this value programmatically during operation of the program it is better to useGDALSetCacheMax()
(always in bytes) or orGDALSetCacheMax64()
. The maximum practical value on 32 bit OS is between 2 and 4 GB. It is the responsibility of the user to set a consistent value.GDAL_FORCE_CACHING=[YES/NO]: Defaults to
NO
. When set to YES,GDALDataset::RasterIO()
andGDALRasterBand::RasterIO()
will use cached IO (access block by block throughGDALRasterBand::IReadBlock()
API) instead of a potential driver-specific implementation of IRasterIO(). This will only have an effect on drivers that specialize IRasterIO() at the dataset or raster band level, for example JP2KAK, NITF, HFA, WCS, ECW, MrSID, and JPEG.GDAL_BAND_BLOCK_CACHE=[AUTO/ARRAY/HASHSET]: Defaults to
AUTO
. Controls whether the block cache should be backed by an array or a hashset. By default (AUTO
) the implementation will be selected based on the number of blocks in the dataset. See RFC 26: GDAL Block Cache Improvements for more information.GDAL_MAX_DATASET_POOL_SIZE=value: Defaults to
100
. Used by gdalproxypool.cppNumber of datasets that can be opened simultaneously by the GDALProxyPool mechanism (used by VRT for example). Can be increased to get better random I/O performance with VRT mosaics made of numerous underlying raster files. Be careful: on Linux systems, the number of file handles that can be opened by a process is generally limited to 1024. This is currently clamped between 2 and 1000.
GDAL_MAX_DATASET_POOL_RAM_USAGE=value: (GDAL >= 3.7) Limit the RAM usage of opened datasets in the GDALProxyPool.
The value can also be suffixed with
MB
orGB
to respectively express it in megabytes or gigabytes. The default value is 25% of the usable physical RAM minus theGDAL_CACHEMAX
value.GDAL_SWATH_SIZE=value: Defaults to
1/4
of the maximum block cache size (``GDAL_CACHEMAX``). Used by rasterio.cppSize of the swath when copying raster data from one dataset to another one (in bytes). Should not be smaller than
GDAL_CACHEMAX
.GDAL_DISABLE_READDIR_ON_OPEN=[TRUE/FALSE/EMPTY_DIR]: Defaults to
FALSE
. By default (FALSE), GDAL establishes a list of all the files in the directory of the file passed toGDALOpen()
. This can result in speed-ups in some use cases, but also to major slow downswhen the directory contains thousands of other files. When set to TRUE, GDAL will not try to establish the list of files. The number of files read can also be limited byGDAL_READDIR_LIMIT_ON_OPEN
.If set to EMPTY_DIR, only the file that is being opened will be seen when a GDAL driver will request sibling files, so this is a way to disable loading side-car/auxiliary files.
GDAL_READDIR_LIMIT_ON_OPEN=value: Defaults to
1000
. Sets the maximum number of files to scan when searching for sidecar files inGDALOpen()
.VSI_CACHE=[TRUE/FALSE]: When using the VSI interface files can be cached in RAM by setting the configuration option
VSI_CACHE
toTRUE
. The cache size defaults to 25 MB, but can be modified by setting the configuration optionVSI_CACHE_SIZE
. (in bytes).When enabled, this cache is used for most I/O in GDAL, including local files.
VSI_CACHE_SIZE=<size in bytes>: Set the size of the VSI cache. Be wary of large values for
VSI_CACHE_SIZE
when opening VRT datasources containing many source rasters, as this is a per-file cache.
Driver management
GDAL_SKIP=space-separated list: Used by
GDALDriverManager::AutoSkipDrivers()
This option can be used to unregister one or several GDAL drivers. This can be useful when a driver tries to open a dataset that it should not recognize, or when several drivers are built-in that can open the same datasets (for example JP2MrSID, JP2ECW, JPEG2000 and JP2KAK for JPEG2000 datasets). The value of this option must be a space delimited list of the short name of the GDAL drivers to unregister.
This option must be set before calling
GDALAllRegister()
, or an explicit call toGDALDriverManager::AutoSkipDrivers()
will be required.OGR_SKIP=comma-separated list: This option can be used to unregister one or several OGR drivers. This can be useful when a driver tries to open a datasource that it should not recognize, or when several drivers are built-in that can open the same datasets (for example KML, LIBKML datasources). The value of this option must be a comma delimited list of the short name of the OGR drivers to unregister.
GDAL_DRIVER_PATH=value: Used by
GDALDriverManager::AutoLoadDrivers()
.This function will automatically load drivers from shared libraries. It searches the "driver path" for .so (or .dll) files that start with the prefix "gdal_X.so". It then tries to load them and then tries to call a function within them called GDALRegister_X() where the 'X' is the same as the remainder of the shared library basename ('X' is case sensitive), or failing that to call GDALRegisterMe().
There are a few rules for the driver path. If the
GDAL_DRIVER_PATH
environment variable it set, it is taken to be a list of directories to search separated by colons on UNIX, or semi-colons on Windows. Otherwise the /usr/local/lib/gdalplugins directory, and (if known) the lib/gdalplugins subdirectory of the gdal home directory are searched on UNIX and $(BINDIR)gdalplugins on Windows.Auto loading can be completely disabled by setting the
GDAL_DRIVER_PATH
config option to "disable".This option must be set before calling
GDALAllRegister()
, or an explicit call toGDALDriverManager::AutoLoadDrivers()
will be required.GDAL_PYTHON_DRIVER_PATH=value: A list of directories to search for
.py
files implementing GDAL drivers. LikeGDAL_DRIVER_PATH
, directory names should be separated by colons on Unix or semi-colons on Windows. For more information, see RFC 76: OGR Python drivers.
General options
GDAL_DATA=<path>: Path to directory containing various GDAL data files (EPSG CSV files, S-57 definition files, DXF header and footer files, ...).
This option is read by the GDAL and OGR driver registration functions. It is used to expand EPSG codes into their description in the OSR model (WKT based).
On some builds (Unix), the value can be hard-coded at compilation time to point to the path after installation (/usr/share/gdal/data for example). On Windows platform, this option must be generally declared.
GDAL_CONFIG_FILE=value: (GDAL >= 3.3) The location of the GDAL config file (see GDAL configuration file).
CPL_TMPDIR=<dirname>: By default, temporary files are written into current working directory. Sometimes this is not optimal and it would be better to write temporary files on bigger or faster drives (SSD).
GDAL_RASTERIO_RESAMPLING=[NEAR/BILINEAR/CUBIC/CUBICSPLINE/LANCZOS/AVERAGE/RMS/MODE/GAUSS]: Defaults to
NEAR
. Sets the resampling algorithm to be used when reading from a raster into a buffer with different dimensions from the source region.CPL_VSIL_ZIP_ALLOWED_EXTENSIONS=<comma-separated list>: Add to zip FS handler default extensions array (zip, kmz, dwf, ods, xlsx) additional extensions listed in
CPL_VSIL_ZIP_ALLOWED_EXTENSIONS
config option.CPL_VSIL_DEFLATE_CHUNK_SIZE=value: Defaults to
1
M.GDAL_DISABLE_CPLLOCALEC=[YES/NO]: Defaults to
NO
. If set to YES (default is NO) this option will disable the normal behavior of the CPLLocaleC class which forces the numeric locale to "C" for selected chunks of code using the setlocale() call. Behavior of setlocale() in multi-threaded applications may be undependable but use of this option may result in problem formatting and interpreting numbers properly.GDAL_FILENAME_IS_UTF8=[YES/NO]: Defaults to
YES
. This option only has an effect on Windows systems (using cpl_vsil_win32.cpp). If set to "NO" then filenames passed to functions likeVSIFOpenL()
will be passed on directly to CreateFile() instead of being converted from UTF-8 to wchar_t and passed to CreateFileW(). This effectively restores the pre-GDAL1.8 behavior for handling filenames on Windows and might be appropriate for applications that treat filenames as being in the local encoding.GDAL_MAX_BAND_COUNT=<integer>: Defaults to
65536
. Defines the maximum number of bands to read from a single dataset.GDAL_XML_VALIDATION=[YES/NO]: Defaults to
YES
. Determines whether XML content should be validated against an XSD, with non-conformities reported as warnings.GDAL_GEOREF_SOURCES=value: Determines the order in which potential georeferencing sources are scanned. Value should be a comma-separated list of sources in order of decreasing priority. The set of sources recognized by this option is driver-specific.
GDAL_OVR_PROPAGATE_NODATA=[YES/NO]: Defaults to
NO
. When computing the value of an overview pixel, determines whether a single NODATA value should cause the overview pixel to be set to NODATA (YES
), or whether the NODATA values should be simply ignored (NO
). This configuration option is not supported for all resampling algorithms/data types.USE_RRD=[YES/NO]: Defaults to
NO
. Used by gdaldefaultoverviews.cppCan be set to YES to use Erdas Imagine format (.aux) as overview format. See gdaladdo documentation.
PYTHONSO=value: Location of Python shared library file, e.g.
pythonX.Y[...].so/.dll
.
Networking options
CPL_VSIL_CURL_ALLOWED_EXTENSIONS=<comma-separated list>: Consider that only the files whose extension ends up with one that is listed in
CPL_VSIL_CURL_ALLOWED_EXTENSIONS
exist on the server. This can speed up dramatically open experience, in case the server cannot return a file list.For example:
gdalinfo --config CPL_VSIL_CURL_ALLOWED_EXTENSIONS ".tif" /vsicurl/http://igskmncngs506.cr.usgs.gov/gmted/Global_tiles_GMTED/075darcsec/bln/W030/30N030W_20101117_gmted_bln075.tif
CPL_VSIL_CURL_CACHE_SIZE=<bytes>: Defaults to
16
MB. Size of global least-recently-used (LRU) cache shared among all downloaded content.CPL_VSIL_CURL_USE_HEAD=[YES/NO]: Defaults to
YES
. Controls whether to use a HEAD request when opening a remote URL.CPL_VSIL_CURL_USE_S3_REDIRECT=[YES/NO]: Defaults to
YES
. Try to query quietly redirected URLs to Amazon S3 signed URLs during their validity period, so as to minimize round-trips.CPL_VSIL_CURL_AUTHORIZATION_HEADER_ALLOWED_IF_REDIRECT=[YES/NO/IF_SAME_HOST]: (GDAL >= 3.10) Defaults to
IF_SAME_HOST
. Determines if the HTTPAuthorization
header must be forwarded when redirections are followed:NO
to always disable forwarding of Authorization headerYES
to always enable forwarding of Authorization header (was the default value prior to GDAL 3.10)IF_SAME_HOST
to enable forwarding of Authorization header only if the redirection is to the same host.
CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE=[YES/NO]: Use a local temporary file to support random writes in certain virtual file systems. The temporary file will be located in
CPL_TMPDIR
.CURL_CA_BUNDLE=value: Set the path to the Certification Authority (CA) bundle file.
SSL_CERT_FILE=value:
CPL_VSIL_CURL_CHUNK_SIZE=<bytes>:
GDAL_INGESTED_BYTES_AT_OPEN=value: Sets the number of bytes read in one GET call at file opening.
CPL_VSIL_CURL_NON_CACHED=<colon-separated list>: A global LRU cache of 16 MB shared among all downloaded content is enabled by default, and content in it may be reused after a file handle has been closed and reopened. The
CPL_VSIL_CURL_NON_CACHED
configuration option can be set to values like/vsis3/bucket/foo.tif:/vsis3/another_bucket/some_directory
, so that at file handle closing, all cached content related to the mentioned file(s) is no longer cached. This can help when dealing with resources that can be modified during execution of GDAL-related code.GDAL_HTTP_HEADER_FILE=<filename>: Filename of a text file with "key: value" HTTP headers. The content of the file is not cached, and thus it is read again before issuing each HTTP request.
GDAL_HTTP_CONNECTTIMEOUT=<seconds>: Maximum delay for connection to be established before being aborted.
GDAL_HTTP_COOKIE=value: Cookie(s) to send. See https://curl.se/libcurl/c/CURLOPT_COOKIE.html
GDAL_HTTP_COOKIEFILE=value: File name to read cookies from. See https://curl.se/libcurl/c/CURLOPT_COOKIEFILE.html
GDAL_HTTP_COOKIEJAR=value: File to which cookies should be written. See https://curl.se/libcurl/c/CURLOPT_COOKIEJAR.html
GDAL_HTTP_NETRC=[YES/NO]: Defaults to
YES
. Controls if an available.netrc
file is used.GDAL_HTTP_NETRC_FILE=<filename>: (GDAL >= 3.7.0) Sets the location of a
.netrc
file.GDAL_HTTP_LOW_SPEED_LIMIT=<bytes/s>: Defaults to
0
. Sets the transfer speed, averaged overGDAL_HTTP_LOW_SPEED_TIME
, below which a request should be canceled.GDAL_HTTP_LOW_SPEED_TIME=<seconds>: Defaults to
0
. Sets the time window over whichGDAL_HTTP_LOW_SPEED_LIMIT
should be evaluated.GDAL_HTTP_SSL_VERIFYSTATUS=[YES/NO]: Defaults to
NO
. Whether to verify the status of SSL certificates. See https://curl.se/libcurl/c/CURLOPT_SSL_VERIFYSTATUS.htmlGDAL_HTTP_USE_CAPI_STORE=[YES/NO]: Defaults to
NO
. (Windows only). Whether to use certificates from the Windows certificate store.GDAL_HTTP_HEADERS=value: (GDAL >= 3.6) Specifies headers as a comma separated list of key: value pairs. If a comma or a double-quote character is needed in the value, then the key: value pair must be enclosed in double-quote characters. In that situation, backslash and double quote character must be backslash-escaped. e.g GDAL_HTTP_HEADERS=Foo: Bar,"Baz: escaped backslash \\, escaped double-quote \", end of value",Another: Header
GDAL_HTTP_MAX_RETRY=value: Defaults to
0
. Set the number of HTTP attempts, when a retry is allowed. (cfGDAL_HTTP_RETRY_CODES
for conditions where a retry is attempted.) The default value is 0, meaning no retry.GDAL_HTTP_RETRY_DELAY=<seconds>: Defaults to
30
. Set the delay between HTTP attempts.GDAL_HTTP_RETRY_CODES=ALL or comma-separated list of codes: (GDAL >= 3.10) Specify which HTTP error codes should trigger a retry attempt. Valid values are
ALL
or a comma-separated list of HTTP codes. By default, 429, 500, 502, 503 or 504 HTTP errors are considered, as well as other situations with a particular HTTP or Curl error message.GDAL_HTTP_TCP_KEEPALIVE=[YES/NO]: (GDAL >= 3.6) Defaults to
NO
. Sets whether to enable TCP keep-alive.GDAL_HTTP_TCP_KEEPIDLE=<seconds>: (GDAL >= 3.6) Defaults to
60
. Keep-alive idle time. Only taken into account ifGDAL_HTTP_TCP_KEEPALIVE=YES
.GDAL_HTTP_TCP_KEEPINTVL=<seconds>: (GDAL >= 3.6) Defaults to
60
. Interval time between keep-alive probes. Only taken into account ifGDAL_HTTP_TCP_KEEPALIVE=YES
.GDAL_HTTP_SSLCERT=<filename>: (GDAL >= 3.7) Filename of the the SSL client certificate. See https://curl.se/libcurl/c/CURLOPT_SSLCERT.html
GDAL_HTTP_SSLCERTTYPE=[PEM/DER]: (GDAL >= 3.7) Format of the SSL certificate. see https://curl.se/libcurl/c/CURLOPT_SSLCERTTYPE.html
GDAL_HTTP_SSLKEY=<filename>: (GDAL >= 3.7) Private key file for TLS and SSL client certificate. see https://curl.se/libcurl/c/CURLOPT_SSLKEY.html
GDAL_HTTP_KEYPASSWD=value: (GDAL >= 3.7) Passphrase to private key. See https://curl.se/libcurl/c/CURLOPT_KEYPASSWD.html
GDAL_HTTP_VERSION=[1.0/1.1/2/2TLS/2PRIOR_KNOWLEDGE]: Specifies which HTTP version to use. Will default to 1.1 generally (except on some controlled environments, like Google Compute Engine VMs, where 2TLS will be the default). Support for HTTP/2 requires curl 7.33 or later, built against nghttp2. "2TLS" means that HTTP/2 will be attempted for HTTPS connections only. Whereas "2" means that HTTP/2 will be attempted for HTTP or HTTPS. "2PRIOR_KNOWLEDGE" means that the server will be assumed to support HTTP/2. The interest of enabling HTTP/2 is the use of HTTP/2 multiplexing when reading GeoTIFFs stored on /vsicurl/ and related virtual file systems.
GDAL_HTTP_MULTIPLEX=[YES/NO]: Defaults to YES. Only applies on a HTTP/2 connection. If set to YES, HTTP/2 multiplexing can be used to download multiple ranges in parallel, during ReadMultiRange() requests that can be emitted by the GeoTIFF driver.
GDAL_HTTP_MULTIRANGE=[SINGLE_GET/SERIAL/YES]: Defaults to
YES
. Controls how ReadMultiRange() requests emitted by the GeoTIFF driver are satisfied. SINGLE_GET means that several ranges will be expressed in the Range header of a single GET requests, which is not supported by a majority of servers (including AWS S3 or Google GCS). SERIAL means that each range will be requested sequentially. YES means that each range will be requested in parallel, using HTTP/2 multiplexing or several HTTP connections.GDAL_HTTP_MERGE_CONSECUTIVE_RANGES=[YES/NO]: Defaults to
YES
. Only applies whenGDAL_HTTP_MULTIRANGE
is YES. Defines if ranges of a single ReadMultiRange() request that are consecutive should be merged into a single request.GDAL_HTTP_AUTH=[BASIC/NTLM/NEGOTIATE/ANY/ANYSAFE/BEARER]: Set value to tell libcurl which authentication method(s) you want it to use. See http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTHTTPAUTH for more information.
GDAL_HTTP_USERPWD=value: The HTTP user and password to use for the connection. Must be in the form of [user name]:[password]. Use
GDAL_HTTP_AUTH
to decide the authentication method.When using NTLM, you can set the domain by prepending it to the user name and separating the domain and name with a forward (/) or backward slash (). Like this: "domain/user:password" or "domainuser:password". Some HTTP servers (on Windows) support this style even for Basic authentication.
GDAL_GSSAPI_DELEGATION=[NONE/POLICY/ALWAYS]: (GDAL >= 3.3) Set allowed GSS-API delegation. Relevant only with
GDAL_HTTP_AUTH=NEGOTIATE
.GDAL_HTTP_BEARER=value: (GDAL >= 3.9) Set HTTP OAuth 2.0 Bearer Access Token to use for the connection. Must be used with
GDAL_HTTP_AUTH=BEARER
.GDAL_HTTP_PROXY=value: Set HTTP proxy to use. The parameter should be the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]: since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies.
GDAL respects the environment variables http_proxy, ftp_proxy, all_proxy etc, if any of those are set. GDAL_HTTP_PROXY option does however override any possibly set environment variables.
GDAL_HTTPS_PROXY=value: Set HTTPS proxy to use. See
GDAL_HTTP_PROXY
.GDAL_HTTP_PROXYUSERPWD=value: The HTTP user and password to use for the connection to the HTTP proxy. Must be in the form of [user name]:[password].
GDAL_PROXY_AUTH=[BASIC/NTLM/NEGOTIATE/DIGEST/ANY/ANYSAFE]: Set value to to tell libcurl which authentication method(s) you want it to use for your proxy authentication. See http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXYAUTH for more information.
CPL_CURL_GZIP=[YES/NO]: Sets the contents of the Accept-Encoding header sent in a HTTP request to gzip, and enables decoding of a response when a Content-Encoding: header
GDAL_HTTP_TIMEOUT=value: Set HTTP timeout value, where value is in seconds
GDAL_HTTP_USERAGENT=value: This string will be used to set the
User-Agent
header in the HTTP request sent to the remote server. Defaults to "GDAL/x.y.z" where x.y.z is the GDAL build version.GDAL_HTTP_UNSAFESSL=[YES/NO]: Defaults to
NO
. Set to "YES" to get the curl library to skip SSL host / certificate verification.
Persistent Auxiliary Metadata (PAM) options
GDAL_PAM_ENABLED=[YES/NO]: PAM support can be enabled (resp. disabled) in GDAL by setting the
GDAL_PAM_ENABLED
configuration option (via CPLSetConfigOption(), or the environment) to the value of YES (resp. NO). Note: The default value is build dependent and defaults to YES in Windows and Unix builds. SeeGDALPamDataset
for more information. Note that setting this option to OFF may have subtle/silent side-effects on various drivers that rely on PAM functionality.GDAL_PAM_PROXY_DIR=value: Directory to which
.aux.xml
files will be written when accessing files from a location where the user does not have write permissions. Has no effect when accessing files from locations where the user does have write permissions. Must be set before the first access to PAM.
PROJ options
CENTER_LONG=value:
CHECK_WITH_INVERT_PROJ=value: Defaults to
NO
. Used by ogrct.cpp and gdalwarp_lib.cpp.This option can be used to control the behavior of gdalwarp when warping global datasets or when transforming from/to polar projections, which causes coordinate discontinuities. See http://trac.osgeo.org/gdal/ticket/2305.
The background is that PROJ does not guarantee that converting from
src_srs
todst_srs
and then fromdst_srs
tosrc_srs
will yield the initial coordinates. This can lead to errors in the computation of the target bounding box of gdalwarp, or to visual artifacts.If
CHECK_WITH_INVERT_PROJ
option is not set, gdalwarp will check that the computed coordinates of the edges of the target image are in the validity area of the target projection. If they are not, it will retry computing them by settingCHECK_WITH_INVERT_PROJ=TRUE
that forces ogrct.cpp to check the consistency of each requested projection result with the inverse projection.If set to
NO
, gdalwarp will not attempt to use the inverse projection.THRESHOLD=value: Defaults to
0.1
for geographic SRS, 10000 otherwise. Used by ogrct.cpp.Used in combination with
CHECK_WITH_INVERT_PROJ=TRUE
. Defines the acceptable threshold used to check if the round-trip fromsrc_srs
todst_srs
and fromdst_srs
tosrs_srs
yields the initial coordinates. The round-trip transformation will be considered successful if thex
andy
values are both withinTHRESHOLD
of the original values. The value must be expressed in the units of the source SRS (typically degrees for a geographic SRS, meters for a projected SRS).OGR_ENABLE_PARTIAL_REPROJECTION=[YES/NO]: Defaults to
NO
. Used byOGRLineString::transform()
.Can be set to YES to remove points that cannot be reprojected. This can for example help reproject lines that have an extremity at a pole, when the reprojection does not support coordinates at poles.
OGR_CT_USE_SRS_COORDINATE_EPOCH=[YES/NO]: If
NO
, disables the coordinate epoch associated with the target or source CRS when transforming between a static and dynamic CRS.OSR_ADD_TOWGS84_ON_EXPORT_TO_WKT1=[YES/NO]: (GDAL >= 3.0.3) Defaults to
NO
. Determines whether aTOWGS84
node should be automatically added when exporting a CRS to the GDAL flavor of WKT1.OSR_ADD_TOWGS84_ON_EXPORT_TO_PROJ4=[YES/NO]: (GDAL >= 3.0.3) Defaults to
YES
. Determines whether a+towgs84
parameter should be automatically added when exporting a CRS as a legacy PROJ.4 string.OSR_ADD_TOWGS84_ON_IMPORT_FROM_EPSG=[YES/NO]: (GDAL >= 3.0.3) Defaults to
NO
. Determines whether to automatically add a 3-parameter or 7-parameter Helmert transformation to WGS84 when there is exactly one such method available for the CRS.OSR_DEFAULT_AXIS_MAPPING_STRATEGY=[TRADITIONAL_GIS_ORDER/AUTHORITY_COMPLIANT]: (GDAL >= 3.5) Defaults to
AUTHORITY_COMPLIANT
. Determines whether to honor the declared axis mapping of a CRS or override it with the traditional GIS ordering (x = longitude, y = latitude).OSR_STRIP_TOWGS84=[YES/NO]: (GDAL >= 3.1) Defaults to
YES
. Determines whether to remove TOWGS84 information if the CRS has a known horizontal datum.OSR_USE_NON_DEPRECATED=[YES/NO]: Defaults to
YES
. Determines whether to substitute a replacement for deprecated EPSG codes.OSR_WKT_FORMAT=[SFSQL/WKT1_SIMPLE/WKT1/WKT1_GDAL/WKT1_ESRI/WKT2_2015/WKT2_2018/WKT2/DEFAULT]: Defaults to
DEFAULT
. Sets the format for writing a CRS to WKT.
List of configuration options and where they are documented
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
: 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_ROLE_ARN
: 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, ...AWS_WEB_IDENTITY_TOKEN_FILE
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...AZURE_IMDS_CLIENT_ID
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...AZURE_IMDS_MSI_RES_ID
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...AZURE_IMDS_OBJECT_ID
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...AZURE_NO_SIGN_REQUEST
: 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_ACCESS_TOKEN
: 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, ...AZURE_STORAGE_SAS_TOKEN
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...CPL_AWS_CREDENTIALS_FILE
: 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_SOZIP_ENABLED
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...CPL_SOZIP_MIN_FILE_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_IGNORE_STORAGE_CLASSES
: 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_VSIS3_CREATE_DIR_OBJECT
: 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, ...CPL_VSISTDIN_BUFFER_LIMIT
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...ECWP_BLOCKING_TIME_MS
: ECW -- Enhanced Compressed Wavelets (.ecw)ECWP_CACHE_LOCATION
: ECW -- Enhanced Compressed Wavelets (.ecw)ECWP_CACHE_SIZE_MB
: ECW -- Enhanced Compressed Wavelets (.ecw)ECWP_REFRESH_TIME_MS
: ECW -- Enhanced Compressed Wavelets (.ecw)ECW_ALWAYS_UPWARD
: ECW -- Enhanced Compressed Wavelets (.ecw)ECW_CACHE_MAXOPEN
: ECW -- Enhanced Compressed Wavelets (.ecw)ECW_FORCE_FILE_REOPEN
: ECW -- Enhanced Compressed Wavelets (.ecw)ECW_RESILIENT_DECODING
: ECW -- Enhanced Compressed Wavelets (.ecw)ES_BULK
: Elasticsearch: Geographically Encoded Objects for ElasticsearchES_META
: Elasticsearch: Geographically Encoded Objects for ElasticsearchES_OVERWRITE
: Elasticsearch: Geographically Encoded Objects for ElasticsearchES_WRITEMAP
: Elasticsearch: Geographically Encoded Objects for ElasticsearchGDAL_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_ERROR_ON_LIBJPEG_WARNING
: JPEG -- JPEG JFIF File FormatGDAL_NETCDF_ASSUME_LONGLAT
: NetCDF: Network Common Data FormGDAL_NETCDF_IGNORE_XY_AXIS_NAME_CHECKS
: NetCDF: Network Common Data FormGDAL_NETCDF_REPORT_EXTRA_DIM_VALUES
: NetCDF: Network Common Data FormGDAL_STACTA_SKIP_MISSING_METATILE
: STACTA - Spatio-Temporal Asset Catalog Tiled AssetsGDAL_TIFF_INTERNAL_MASK_TO_8BIT
: GTiff -- GeoTIFF File FormatGML_ATTRIBUTES_TO_OGR_FIELDS
: GML - Geography Markup LanguageGRIB_ADJUST_LONGITUDE_RANGE
: GRIB -- WMO General Regularly-distributed Information in Binary formGRIB_NORMALIZE_UNITS
: GRIB -- WMO General Regularly-distributed Information in Binary formGRIB_RESOURCE_DIR
: GRIB -- WMO General Regularly-distributed Information in Binary formGS_ACCESS_KEY_ID
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...GS_NO_SIGN_REQUEST
: 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_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, ...GS_USER_PROJECT
: GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...GTIFF_READ_ANGULAR_PARAMS_IN_DEGREE
: GTiff -- GeoTIFF File FormatGTIFF_WRITE_ANGULAR_PARAMS_IN_DEGREE
: GTiff -- GeoTIFF File FormatLIBKML_NETWORKLINK_FLYTOVIEW_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_HTTPQUERY_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_REFRESHINTERVAL_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_REFRESHMODE_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_REFRESHVISIBILITY_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_VIEWBOUNDSCALE_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_VIEWREFRESHMODE_FIELD
: LIBKML Driver (.kml .kmz)LIBKML_NETWORKLINK_VIEWREFRESHTIME_FIELD
: LIBKML Driver (.kml .kmz)LURA_LICENSE_NUM_1
: JP2Lura -- JPEG2000 driver based on Lurawave libraryLURA_LICENSE_NUM_2
: JP2Lura -- JPEG2000 driver based on Lurawave libraryMSSQLSPATIAL_ALWAYS_OUTPUT_FID
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_BCP_SIZE
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_LIST_ALL_TABLES
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_OGR_FID
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_SHOW_FID_COLUMN
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_USE_BCP
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_USE_GEOMETRY_COLUMNS
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseMSSQLSPATIAL_USE_GEOMETRY_VALIDATION
: MSSQLSpatial - Microsoft SQL Server Spatial DatabaseOGR_JSONFG_MAX_OBJ_SIZE
: JSONFG -- OGC Features and Geometries JSONOGR_VFK_DB_DELETE
: VFK - Czech Cadastral Exchange Data FormatOGR_VFK_DB_OVERWRITE
: VFK - Czech Cadastral Exchange Data FormatOGR_VFK_DB_READ_ALL_BLOCKS
: VFK - Czech Cadastral Exchange Data FormatOGR_VFK_DB_SPATIAL
: VFK - Czech Cadastral Exchange Data FormatOPENFILEGDB_DEFAULT_STRING_WIDTH
: ESRI File Geodatabase vector (OpenFileGDB)OPENFILEGDB_IN_MEMORY_SPI
: ESRI File Geodatabase vector (OpenFileGDB)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, ...PLSCENES_PAGE_SIZE
: PLScenes (Planet Labs Scenes), Data V1 APISWIFT_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, ...USE_TILE_AS_BLOCK
: JP2KAK -- JPEG 2000 (based on Kakadu SDK)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, ...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, ...