GDAL-RASTER-TILE(1) GDAL GDAL-RASTER-TILE(1)
gdal-raster-tile - Generate tiles in separate files from a raster
dataset
Added in version 3.11.
Usage: gdal raster tile [OPTIONS] <INPUT> <OUTPUT>
Generate tiles in separate files from a raster dataset.
Positional arguments:
-i, --dataset, --input <INPUT> Input raster datasets [required]
-o, --output <OUTPUT> Output directory [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format (default: PNG)
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--tiling-scheme <TILING-SCHEME> Tiling scheme. TILING-SCHEME=raster|WebMercatorQuad|WorldCRS84Quad|WorldMercatorWGS84Quad|GoogleCRS84Quad|PseudoTMS_GlobalMercator|LINZAntarticaMapTilegrid|APSTILE|CBMTILE|NZTM2000 (default: WebMercatorQuad)
--min-zoom <MIN-ZOOM> Minimum zoom level
--max-zoom <MAX-ZOOM> Maximum zoom level
--min-x <MIN-X> Minimum tile X coordinate
--max-x <MAX-X> Maximum tile X coordinate
--min-y <MIN-Y> Minimum tile Y coordinate
--max-y <MAX-Y> Maximum tile Y coordinate
--no-intersection-ok Whether dataset extent not intersecting tile matrix is only a warning
-r, --resampling <RESAMPLING> Resampling method for max zoom. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum (default: cubic)
--overview-resampling <OVERVIEW-RESAMPLING> Resampling method for overviews. OVERVIEW-RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
--convention <CONVENTION> Tile numbering convention: xyz (from top) or tms (from bottom). CONVENTION=xyz|tms (default: xyz)
--tile-size <TILE-SIZE> Override default tile size
--add-alpha Whether to force adding an alpha channel
Mutually exclusive with --no-alpha
--no-alpha Whether to disable adding an alpha channel
Mutually exclusive with --add-alpha
--dst-nodata <DST-NODATA> Destination nodata value
--skip-blank Do not generate blank tiles
--metadata <KEY>=<VALUE> Add metadata item to output tiles [may be repeated]
--copy-src-metadata Whether to copy metadata from source dataset
--aux-xml Generate .aux.xml sidecar files when needed
--kml Generate KML files
--resume Generate only missing files
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: ALL_CPUS)
--parallel-method <PARALLEL-METHOD> Parallelization method (thread, spawn, fork). PARALLEL-METHOD=thread|spawn|fork
Advanced Options:
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
Advanced Resampling Options:
--excluded-values <EXCLUDED-VALUES> Tuples of values (e.g. <R>,<G>,<B> or (<R1>,<G1>,<B1>),(<R2>,<G2>,<B2>)) that must beignored as contributing source pixels during (average) resampling
--excluded-values-pct-threshold <EXCLUDED-VALUES-PCT-THRESHOLD> Minimum percentage of source pixels that must be set at one of the --excluded-values to cause the excluded value to be used as the target pixel value (default: 50)
--nodata-values-pct-threshold <NODATA-VALUES-PCT-THRESHOLD> Minimum percentage of source pixels that must be set at one of nodata (or alpha=0 or any other way to express transparent pixelto cause the target pixel value to be transparent (default: 100)
Publication Options:
--webviewer <WEBVIEWER> Web viewer to generate. WEBVIEWER=none|all|leaflet|openlayers|mapml|stac (default: all) [may be repeated]
--url <URL> URL address where the generated tiles are going to be published
--title <TITLE> Title of the map
--copyright <COPYRIGHT> Copyright for the map
--mapml-template <MAPML-TEMPLATE> Filename of a template mapml file where variables will be substituted
gdal raster tile generates a directory with small tiles and metadata,
following the OGC WMTS Specification. Simple web pages with viewers
based on OpenLayers and Leaflet are generated as well - so anybody
can comfortably explore your maps on-line and you do not need to
install or configure any special software (like MapServer) and the
map displays very fast in the web browser. You only need to upload
the generated directory onto a web server.
It generates PNG files by default, but other output formats can be
selected (JPEG, WEBP, GTiff, etc.). Note that not all formats support
non-Byte data types. JPEG and WEBP only support Byte. PNG supports
Byte and UInt16. GeoTiff can support all data types.
It can also use a tiling scheme fully adapted to the input raster, in
terms of origin and resolution, when using the raster tiling scheme.
In that scheme, tiles at the maximum zoom level will have the same
resolution as the raster.
Starting with GDAL 3.12, gdal raster tile can be used as the last
step of a pipeline.
-i, --input <INPUT>
Input raster dataset [required]
-o, --output <OUTPUT>
Output directory [required]
The directory will be created if it does not exist, but its
parent directory must exist.
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
Defaults to PNG.
--co, --creation-option <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.
May be repeated.
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.
--tiling-scheme <TILING-SCHEME>
Tile cutting scheme. Defaults to WebMercatorQuad (also known
as Google Maps compatible).
The following base profiles are available:
+o raster: CRS = CRS of raster, tile size = 256 pixels, raster
coverage at all zoom levels.
+o WebMercatorQuad: CRS = EPSG:3857 ("WGS 84 /
Pseudo-Mercator"), tile size: 256 pixels, whole world
coverage at zoom level 0, one single tile at zoom level 0.
+o WorldCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256
pixels, whole world coverage at zoom level 0, two
side-by-side tiles at zoom level 0
+o WorldMercatorWGS84Quad: CRS = EPSG:3395 ("WGS 84 / World
Mercator"), tile size: 256 pixels, whole world coverage at
zoom level 0, one single tile at zoom level 0. This can be
seen as a variant of WebMercatorQuad except that it is fully
conformal on the WGS84 ellipsoid.
+o GoogleCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256
pixels, whole world coverage at zoom level 0, one single
tile at zoom level 0 whose first and last 64 lines are blank
(the top origin of the tile is a pseudo latitude of 180
degree, and its bottom -180 degree).
+o PseudoTMS_GlobalMercator: CRS = EPSG:3857 ("WGS 84 /
Pseudo-Mercator"), tile size: 256 pixels, whole world
coverage at zoom level 0, 2x2 tiles at zoom level 0. This is
equivalent to WebMercatorQuad, but with the zoom level
shifted by one.
+o LINZAntarticaMapTileGrid: LINZ Antarctic Map Tile Grid (Ross
Sea Region). See tms_LINZAntarticaMapTileGrid.json
+o APSTILE: Alaska Polar Stereographic-based tiled coordinate
reference system for the Arctic region. See
tms_MapML_APSTILE.json
+o CBMTILE: Lambert Conformal Conic-based tiled coordinate
reference system for Canada. See tms_MapML_CBMTILE.json
+o NZTM2000: LINZ NZTM2000 Map Tile Grid. See tms_NZTM2000.json
Additional tiling schemes are discovered from tms_XXXX.json
files placed in the GDAL data directory.
--min-zoom <MIN-ZOOM>
Minimum zoom level to generate. If not specified, equal to
--max-zoom.
--max-zoom <MAX-ZOOM>
Maximum zoom level to generate. If not specified, this will be
determined by comparing the resolution of the input dataset
with the closest resolution in the list of tile matrix of the
tile matrix set.
--min-x <MIN-X>
Minimum tile X coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--min-y <MIN-Y>
Minimum tile Y coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--max-x <MAX-X>
Maximum tile X coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--max-y <MAX-Y>
Maximum tile Y coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--no-intersection-ok
Whether the dataset extent not intersecting the tile matrix is
only a warning. Otherwise, by default, an error will be
emitted if that occurs.
-r, --resampling
nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate maximum zoom level, and
also lower zoom levels if --overview-resampling is not
specified. Defaults to cubic.
--overview-resampling
nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate zoom levels lower than the
maximum zoom level. Defaults to the value of --resampling is
not specified.
--convention xyz|tms
Tile numbering convention:
+o xyz (default): from top, as in OGC Web Map Tiling
Specification (WMTS)
+o tms: from bottom, as in OSGeo Tile Map Service (TMS)
Specification.
--tile-size <PIXELS>
Width and height of a tile, in pixels. Default is 256 for
default tiling schemes. Setting it to a higher value enables
generating higher DPI tile sets.
--add-alpha
Whether to force adding an alpha channel. An alpha channel is
added by default, unless the source dataset has a nodata value
and the output format supports it.
--no-alpha
Disable the creation of an alpha channel.
--dst-nodata <DSTNODATA>
Destination nodata value.
--skip-blank
Do not generate fully blank/transparent tiles.
--metadata <KEY>=<VALUE>
Add metadata item to output tiles [may be repeated]
--copy-src-metadata
Whether to copy metadata from source dataset into output
tiles.
--aux-xml
Generate .aux.xml sidecar files when needed
--kml Generate Google Earth SuperOverlay metadata. Not compatible
with tiling schemes with non-power-of-two zoom levels.
--resume
Generate only missing files. Can be used when interrupting a
previous run to restart it.
-j, --num-threads <value>
Number of jobs to run at once. Default: number of CPUs
detected.
--parallel-method thread|spawn|fork
Added in version GDAL: 3.12
Parallelization method:
+o thread uses multi-threading, i.e. parallelized tasks are run
within the same process.
+o spawn launches child gdal sub-processes. spawn can achieve
better "scaling", but requires the gdal binary to be
available. GDAL will try to locate it, but you can also set
the GDAL_PATH configuration option to point to the directory
where the gdal binary is located.
+o fork is a variant of spawn, using the system call fork,
without executing the the gdal binary. Such method is not
available on Windows. On Unix systems where it is available,
this method is not recommended to be used on multithreaded
processes, especially the ones where other threads are doing
GDAL operation, since it can potentially cause deadlocks.
If --parallel-method is not specified, GDAL will automatically
decide which of the method is the most appropriate, opting for
spawn if the gdal binary can be located and a sufficient
number of tiles per job are generated, and otherwise falling
back to fork on Linux, MacOSX or FreeBSD (if no other thread
is running), and otherwise to thread.
--excluded-values=<EXCLUDED-VALUES>
Comma-separated tuple of values (thus typically "R,G,B"), that
are ignored as contributing source pixels during resampling.
The number of values in the tuple must be the same as the
number of bands, excluding the alpha band. Several tuples of
excluded values may be specified using the
"(R1,G1,B2),(R2,G2,B2)" syntax. Only taken into account for
average resampling. This concept is a bit similar to
nodata/alpha, but the main difference is that pixels matching
one of the excluded value tuples are still considered as
valid, when determining the target pixel validity/density.
Added in version 3.11.1.
--excluded-values-pct-threshold=<EXCLUDED-VALUES-PCT-THRESHOLD>
Minimum percentage of source pixels that must be set at one of
the --excluded-values to cause the excluded value, that is in
majority among source pixels, to be used as the target pixel
value. Default value is 50(%)
Added in version 3.11.1.
--nodata-values-pct-threshold=<NODATA-VALUES-PCT-THRESHOLD>
Minimum percentage of source pixels that must be at nodata (or
alpha=0 or any other way to express transparent pixel) to
cause the target pixel value to be transparent. Default value
is 100 (%), which means that a target pixel is transparent
only if all contributing source pixels are transparent. Only
taken into account for average resampling.
Added in version 3.11.1.
--webviewer none|all|leaflet|openlayers|mapml|stac
Web viewer to generate. Defaults to all. Those web viewers are
created at the root of the output directory.
stac generates a stacta.json file, following the
Spatio-Temporal Asset Catalog Tiled Assets specification, and
that can be opened by the STACTA driver.
--url URL address where the generated tiles are going to be
published.
--title <TITLE>
Title of the map.
--copyright <COPYRIGHT>
Copyright for the map.
MapML webviewer can only be generated if --convention is set to the
default value xyz.
The following profiles are supported:
+o WebMercatorQuad: mapped to OSMTILE MapML tiling scheme
+o GoogleCRS84Quad: mapped to WGS84 MapML tiling scheme
+o APSTILE: from the tms_MapML_APSTILE.json data file
+o CBMTILE: from the tms_MapML_CBMTILE.json data file
The generated MapML file in the output directory is mapml.mapl
Available options are:
--mapml-template <filename>
Filename of a template mapml file where variables will be
substituted. If not specified, the generic
template_tiles.mapml file from GDAL data resources will be
used
The --url option is also used to substitute ${URL} in the template
MapML file.
Example 1: Generate PNG tiles with WebMercatorQuad tiling scheme for zoom
levels 2 to 5.
gdal raster tile --min-zoom=2 --max-zoom=5 input.tif output_folder
Example 2: Retile a raster using its origin and resolution
gdal raster tile --tiling-scheme raster input.tif output_folder
Example 3: Creating a tiled dataset, compatible of the Spatio-Temporal
Asset Catalog Tiled Assets specification, using Cloud-Optimized
GeoTIFF metatiles of dimension 4096x4096.
gdal raster tile --format COG --tile-size 4096 input.tif output_folder
Example 4: Mosaic on-the-fly several input files and tile that mosaic.
gdal raster pipeline ! mosaic input*.tif ! tile output_folder
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDAL-RASTER-TILE(1)
NAME
gdal-raster-tile - Generate tiles in separate files from a raster
dataset
Added in version 3.11.
SYNOPSIS
Usage: gdal raster tile [OPTIONS] <INPUT> <OUTPUT>
Generate tiles in separate files from a raster dataset.
Positional arguments:
-i, --dataset, --input <INPUT> Input raster datasets [required]
-o, --output <OUTPUT> Output directory [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format (default: PNG)
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--tiling-scheme <TILING-SCHEME> Tiling scheme. TILING-SCHEME=raster|WebMercatorQuad|WorldCRS84Quad|WorldMercatorWGS84Quad|GoogleCRS84Quad|PseudoTMS_GlobalMercator|LINZAntarticaMapTilegrid|APSTILE|CBMTILE|NZTM2000 (default: WebMercatorQuad)
--min-zoom <MIN-ZOOM> Minimum zoom level
--max-zoom <MAX-ZOOM> Maximum zoom level
--min-x <MIN-X> Minimum tile X coordinate
--max-x <MAX-X> Maximum tile X coordinate
--min-y <MIN-Y> Minimum tile Y coordinate
--max-y <MAX-Y> Maximum tile Y coordinate
--no-intersection-ok Whether dataset extent not intersecting tile matrix is only a warning
-r, --resampling <RESAMPLING> Resampling method for max zoom. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum (default: cubic)
--overview-resampling <OVERVIEW-RESAMPLING> Resampling method for overviews. OVERVIEW-RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
--convention <CONVENTION> Tile numbering convention: xyz (from top) or tms (from bottom). CONVENTION=xyz|tms (default: xyz)
--tile-size <TILE-SIZE> Override default tile size
--add-alpha Whether to force adding an alpha channel
Mutually exclusive with --no-alpha
--no-alpha Whether to disable adding an alpha channel
Mutually exclusive with --add-alpha
--dst-nodata <DST-NODATA> Destination nodata value
--skip-blank Do not generate blank tiles
--metadata <KEY>=<VALUE> Add metadata item to output tiles [may be repeated]
--copy-src-metadata Whether to copy metadata from source dataset
--aux-xml Generate .aux.xml sidecar files when needed
--kml Generate KML files
--resume Generate only missing files
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: ALL_CPUS)
--parallel-method <PARALLEL-METHOD> Parallelization method (thread, spawn, fork). PARALLEL-METHOD=thread|spawn|fork
Advanced Options:
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
Advanced Resampling Options:
--excluded-values <EXCLUDED-VALUES> Tuples of values (e.g. <R>,<G>,<B> or (<R1>,<G1>,<B1>),(<R2>,<G2>,<B2>)) that must beignored as contributing source pixels during (average) resampling
--excluded-values-pct-threshold <EXCLUDED-VALUES-PCT-THRESHOLD> Minimum percentage of source pixels that must be set at one of the --excluded-values to cause the excluded value to be used as the target pixel value (default: 50)
--nodata-values-pct-threshold <NODATA-VALUES-PCT-THRESHOLD> Minimum percentage of source pixels that must be set at one of nodata (or alpha=0 or any other way to express transparent pixelto cause the target pixel value to be transparent (default: 100)
Publication Options:
--webviewer <WEBVIEWER> Web viewer to generate. WEBVIEWER=none|all|leaflet|openlayers|mapml|stac (default: all) [may be repeated]
--url <URL> URL address where the generated tiles are going to be published
--title <TITLE> Title of the map
--copyright <COPYRIGHT> Copyright for the map
--mapml-template <MAPML-TEMPLATE> Filename of a template mapml file where variables will be substituted
DESCRIPTION
gdal raster tile generates a directory with small tiles and metadata,
following the OGC WMTS Specification. Simple web pages with viewers
based on OpenLayers and Leaflet are generated as well - so anybody
can comfortably explore your maps on-line and you do not need to
install or configure any special software (like MapServer) and the
map displays very fast in the web browser. You only need to upload
the generated directory onto a web server.
It generates PNG files by default, but other output formats can be
selected (JPEG, WEBP, GTiff, etc.). Note that not all formats support
non-Byte data types. JPEG and WEBP only support Byte. PNG supports
Byte and UInt16. GeoTiff can support all data types.
It can also use a tiling scheme fully adapted to the input raster, in
terms of origin and resolution, when using the raster tiling scheme.
In that scheme, tiles at the maximum zoom level will have the same
resolution as the raster.
Starting with GDAL 3.12, gdal raster tile can be used as the last
step of a pipeline.
Standard options
-i, --input <INPUT>
Input raster dataset [required]
-o, --output <OUTPUT>
Output directory [required]
The directory will be created if it does not exist, but its
parent directory must exist.
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
Defaults to PNG.
--co, --creation-option <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.
May be repeated.
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.
--tiling-scheme <TILING-SCHEME>
Tile cutting scheme. Defaults to WebMercatorQuad (also known
as Google Maps compatible).
The following base profiles are available:
+o raster: CRS = CRS of raster, tile size = 256 pixels, raster
coverage at all zoom levels.
+o WebMercatorQuad: CRS = EPSG:3857 ("WGS 84 /
Pseudo-Mercator"), tile size: 256 pixels, whole world
coverage at zoom level 0, one single tile at zoom level 0.
+o WorldCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256
pixels, whole world coverage at zoom level 0, two
side-by-side tiles at zoom level 0
+o WorldMercatorWGS84Quad: CRS = EPSG:3395 ("WGS 84 / World
Mercator"), tile size: 256 pixels, whole world coverage at
zoom level 0, one single tile at zoom level 0. This can be
seen as a variant of WebMercatorQuad except that it is fully
conformal on the WGS84 ellipsoid.
+o GoogleCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256
pixels, whole world coverage at zoom level 0, one single
tile at zoom level 0 whose first and last 64 lines are blank
(the top origin of the tile is a pseudo latitude of 180
degree, and its bottom -180 degree).
+o PseudoTMS_GlobalMercator: CRS = EPSG:3857 ("WGS 84 /
Pseudo-Mercator"), tile size: 256 pixels, whole world
coverage at zoom level 0, 2x2 tiles at zoom level 0. This is
equivalent to WebMercatorQuad, but with the zoom level
shifted by one.
+o LINZAntarticaMapTileGrid: LINZ Antarctic Map Tile Grid (Ross
Sea Region). See tms_LINZAntarticaMapTileGrid.json
+o APSTILE: Alaska Polar Stereographic-based tiled coordinate
reference system for the Arctic region. See
tms_MapML_APSTILE.json
+o CBMTILE: Lambert Conformal Conic-based tiled coordinate
reference system for Canada. See tms_MapML_CBMTILE.json
+o NZTM2000: LINZ NZTM2000 Map Tile Grid. See tms_NZTM2000.json
Additional tiling schemes are discovered from tms_XXXX.json
files placed in the GDAL data directory.
--min-zoom <MIN-ZOOM>
Minimum zoom level to generate. If not specified, equal to
--max-zoom.
--max-zoom <MAX-ZOOM>
Maximum zoom level to generate. If not specified, this will be
determined by comparing the resolution of the input dataset
with the closest resolution in the list of tile matrix of the
tile matrix set.
--min-x <MIN-X>
Minimum tile X coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--min-y <MIN-Y>
Minimum tile Y coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--max-x <MAX-X>
Maximum tile X coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--max-y <MAX-Y>
Maximum tile Y coordinate, at maximum zoom level. Can be set
to restrict the tiling process.
--no-intersection-ok
Whether the dataset extent not intersecting the tile matrix is
only a warning. Otherwise, by default, an error will be
emitted if that occurs.
-r, --resampling
nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate maximum zoom level, and
also lower zoom levels if --overview-resampling is not
specified. Defaults to cubic.
--overview-resampling
nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate zoom levels lower than the
maximum zoom level. Defaults to the value of --resampling is
not specified.
--convention xyz|tms
Tile numbering convention:
+o xyz (default): from top, as in OGC Web Map Tiling
Specification (WMTS)
+o tms: from bottom, as in OSGeo Tile Map Service (TMS)
Specification.
--tile-size <PIXELS>
Width and height of a tile, in pixels. Default is 256 for
default tiling schemes. Setting it to a higher value enables
generating higher DPI tile sets.
--add-alpha
Whether to force adding an alpha channel. An alpha channel is
added by default, unless the source dataset has a nodata value
and the output format supports it.
--no-alpha
Disable the creation of an alpha channel.
--dst-nodata <DSTNODATA>
Destination nodata value.
--skip-blank
Do not generate fully blank/transparent tiles.
--metadata <KEY>=<VALUE>
Add metadata item to output tiles [may be repeated]
--copy-src-metadata
Whether to copy metadata from source dataset into output
tiles.
--aux-xml
Generate .aux.xml sidecar files when needed
--kml Generate Google Earth SuperOverlay metadata. Not compatible
with tiling schemes with non-power-of-two zoom levels.
--resume
Generate only missing files. Can be used when interrupting a
previous run to restart it.
-j, --num-threads <value>
Number of jobs to run at once. Default: number of CPUs
detected.
--parallel-method thread|spawn|fork
Added in version GDAL: 3.12
Parallelization method:
+o thread uses multi-threading, i.e. parallelized tasks are run
within the same process.
+o spawn launches child gdal sub-processes. spawn can achieve
better "scaling", but requires the gdal binary to be
available. GDAL will try to locate it, but you can also set
the GDAL_PATH configuration option to point to the directory
where the gdal binary is located.
+o fork is a variant of spawn, using the system call fork,
without executing the the gdal binary. Such method is not
available on Windows. On Unix systems where it is available,
this method is not recommended to be used on multithreaded
processes, especially the ones where other threads are doing
GDAL operation, since it can potentially cause deadlocks.
If --parallel-method is not specified, GDAL will automatically
decide which of the method is the most appropriate, opting for
spawn if the gdal binary can be located and a sufficient
number of tiles per job are generated, and otherwise falling
back to fork on Linux, MacOSX or FreeBSD (if no other thread
is running), and otherwise to thread.
Advanced Resampling Options
--excluded-values=<EXCLUDED-VALUES>
Comma-separated tuple of values (thus typically "R,G,B"), that
are ignored as contributing source pixels during resampling.
The number of values in the tuple must be the same as the
number of bands, excluding the alpha band. Several tuples of
excluded values may be specified using the
"(R1,G1,B2),(R2,G2,B2)" syntax. Only taken into account for
average resampling. This concept is a bit similar to
nodata/alpha, but the main difference is that pixels matching
one of the excluded value tuples are still considered as
valid, when determining the target pixel validity/density.
Added in version 3.11.1.
--excluded-values-pct-threshold=<EXCLUDED-VALUES-PCT-THRESHOLD>
Minimum percentage of source pixels that must be set at one of
the --excluded-values to cause the excluded value, that is in
majority among source pixels, to be used as the target pixel
value. Default value is 50(%)
Added in version 3.11.1.
--nodata-values-pct-threshold=<NODATA-VALUES-PCT-THRESHOLD>
Minimum percentage of source pixels that must be at nodata (or
alpha=0 or any other way to express transparent pixel) to
cause the target pixel value to be transparent. Default value
is 100 (%), which means that a target pixel is transparent
only if all contributing source pixels are transparent. Only
taken into account for average resampling.
Added in version 3.11.1.
Publication Options
--webviewer none|all|leaflet|openlayers|mapml|stac
Web viewer to generate. Defaults to all. Those web viewers are
created at the root of the output directory.
stac generates a stacta.json file, following the
Spatio-Temporal Asset Catalog Tiled Assets specification, and
that can be opened by the STACTA driver.
--url URL address where the generated tiles are going to be
published.
--title <TITLE>
Title of the map.
--copyright <COPYRIGHT>
Copyright for the map.
MapML options
MapML webviewer can only be generated if --convention is set to the
default value xyz.
The following profiles are supported:
+o WebMercatorQuad: mapped to OSMTILE MapML tiling scheme
+o GoogleCRS84Quad: mapped to WGS84 MapML tiling scheme
+o APSTILE: from the tms_MapML_APSTILE.json data file
+o CBMTILE: from the tms_MapML_CBMTILE.json data file
The generated MapML file in the output directory is mapml.mapl
Available options are:
--mapml-template <filename>
Filename of a template mapml file where variables will be
substituted. If not specified, the generic
template_tiles.mapml file from GDAL data resources will be
used
The --url option is also used to substitute ${URL} in the template
MapML file.
EXAMPLES
Example 1: Generate PNG tiles with WebMercatorQuad tiling scheme for zoom
levels 2 to 5.
gdal raster tile --min-zoom=2 --max-zoom=5 input.tif output_folder
Example 2: Retile a raster using its origin and resolution
gdal raster tile --tiling-scheme raster input.tif output_folder
Example 3: Creating a tiled dataset, compatible of the Spatio-Temporal
Asset Catalog Tiled Assets specification, using Cloud-Optimized
GeoTIFF metatiles of dimension 4096x4096.
gdal raster tile --format COG --tile-size 4096 input.tif output_folder
Example 4: Mosaic on-the-fly several input files and tile that mosaic.
gdal raster pipeline ! mosaic input*.tif ! tile output_folder
AUTHOR
Even Rouault <even.rouault@spatialys.com>
COPYRIGHT
1998-2026
March 20, 2026 GDAL-RASTER-TILE(1)