Common options for raster programs
All GDAL command line programs support the following common options.
- --version
Report the version of GDAL and exit.
- --build
Report detailed information about GDAL in use.
- --formats
List all raster formats supported by this GDAL build (read-only and read-write) and exit.
The format support is indicated as follows:
ro
is read-only driverrw
is read or write (i.e. supportsGDALDriver::CreateCopy()
)rw+
is read, write and update (i.e. supportsGDALDriver::Create()
)A
v
is appended for formats supporting virtual IO (/vsimem, /vsigzip, /vsizip, etc).A
s
is appended for formats supporting subdatasets.
The order in which drivers are listed is the one in which they are registered, which determines the order in which they are successively probed when opening a dataset. Most of the time, this order does not matter, but in some situations, several drivers may recognize the same file. The
-if
option of some utilities can be specified to restrict opening the dataset with a subset of drivers (generally one). Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions. Alternatively, theGDAL_SKIP
configuration option can also be used to exclude one or several drivers.
- --format <format>
List detailed information about a single format driver. The format should be the short name reported in the --formats list, such as GTiff.
- --formats
List all drivers. Can be combined with
-json
switch of gdalinfo of since GDAL 3.10
- --optfile <filename>
Read the named file and substitute the contents into the command line options list. Lines beginning with # will be ignored. Multi-word arguments may be kept together with double quotes. Multiple --optfiles may be used: --optfile file1 --optfile file2...
- --config <key> <value>
Sets the named configuration keyword to the given value, as opposed to setting them as environment variables. Some common configuration keywords are
GDAL_CACHEMAX
(memory used internally for caching in megabytes) andGDAL_DATA
(path of the GDAL "data" directory). Individual drivers may be influenced by other configuration options.
- --debug <value>
Control what debugging messages are emitted. A value of ON will enable all debug messages. A value of OFF will disable all debug messages. Another value will select only debug messages containing that string in the debug prefix code.
- --help-general
Gives a brief usage message for the generic GDAL command line options and exit.
Creating new files
Access an existing file to read it is generally quite simple. Just indicate the name of the file or dataset on the command line. However, creating a file is more complicated. It may be necessary to indicate the format to create, various creation options affecting how it will be created and perhaps a coordinate system to be assigned. Many of these options are handled similarly by different GDAL utilities, and are introduced here.
- -of <format>
Select the format to create the new file as. The formats are assigned short names such as GTiff (for GeoTIFF) or HFA (for Erdas Imagine). The list of all format codes can be listed with the
--formats
switch. Only formats list as(rw)
(read-write) can be written.Added in version 2.3: If not specified, the format is guessed from the extension. Previously, it was generally GTiff for raster, or ESRI Shapefile for vector.
- -co <NAME>=<VALUE>
Many formats have one or more optional creation options that can be used to control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled.
The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --formats command line option but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.
- -a_srs <srs>
- -s_srs <srs>
- -t_srs <srs>
Several utilities (e.g. gdal_translate and gdalwarp) include the ability to specify coordinate systems with command line options like
-a_srs
(assign SRS to output),-s_srs
(source SRS) and-t_srs
(target SRS). These utilities allow the coordinate system (SRS = spatial reference system) to be assigned in a variety of formats.NAD27|NAD83|WGS84|WGS72
These common geographic (lat/long) coordinate systems can be used directly by these names.
EPSG:n
Coordinate systems (projected or geographic) can be selected based on their EPSG codes. For instance,
EPSG:27700
is the British National Grid. A list of EPSG coordinate systems can be found in the GDAL data filesgcs.csv
andpcs.csv
.PROJ.4 definition
A PROJ.4 definition string can be used as a coordinate system. Take care to keep the proj.4 string together as a single argument to the command (usually by double quoting).
For instance
+proj=utm +zone=11 +datum=WGS84
.OpenGIS Well Known Text
The Open GIS Consortium has defined a textual format for describing coordinate systems as part of the Simple Features specifications. This format is the internal working format for coordinate systems used in GDAL. The name of a file containing a WKT coordinate system definition may be used a coordinate system argument, or the entire coordinate system itself may be used as a command line option (though escaping all the quotes in WKT is quite challenging).
ESRI Well Known Text
ESRI uses a slight variation on OGC WKT format in their ArcGIS product (ArcGIS
.prj
files), and these may be used in a similar manner o WKT files, but the filename should be prefixed withESRI::
.For example, "ESRI::NAD 1927 StatePlane Wyoming West FIPS 4904.prj".
Spatial References from URLs
filename
File containing WKT, PROJ.4 strings, or XML/GML coordinate system definitions can be provided.