GDAL2TILES(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

🌸 GDAL2TILES 🌸

okay bestie, gather round, because this is gdal2tiles, one of the GDAL tools, and it's literally the "make me a whole slippy map website out of my raster" button. full manual page, part 1 of 2, no skips, no cuts. let's go 💅

✨ NAME ✨

gdal2tiles — Generates directory with TMS tiles, KMLs and simple web viewers.

🎀 SYNOPSIS 🎀

gdal2tiles [--help] [--help-general]
              [--legacy]
              [-p <profile>] [-r resampling] [-s <srs>] [-z <zoom>]
              [-e] [-a nodata] [-v] [-q] [-h] [-k] [-n] [-u <url>]
              [-w <webviewer>] [-t <title>] [-c <copyright>]
              [--processes=<NB_PROCESSES>] [--mpi] [--xyz]
              [--tilesize=<PIXELS>] --tiledriver=<DRIVER> [--tmscompatible]
              [--excluded-values=<EXCLUDED_VALUES>]
              [--excluded-values-pct-threshold=<EXCLUDED_VALUES_PCT_THRESHOLD>]
              [--nodata-values-pct-threshold=<NODATA_VALUES_PCT_THRESHOLD>]
              [-g <googlekey] [-b <bingkey>] <input_file> [<output_dir>] [<COMMON_OPTIONS>]

🦋 DESCRIPTION 🦋

WARNING: Starting with GDAL 3.13, gdal2tiles is deprecated, and by default is remapped to gdal raster tile. For now, you may force the use of the legacy code by specifying --legacy, but legacy mode will be removed in GDAL 3.15. If you find yourself to need legacy mode and cannot find workarounds using gdal raster tile, please file a ticket at https://github.com/OSGeo/GDAL

so, what does this icon do? it generates a whole directory of little tiles plus metadata, following the OSGeo Tile Map Service Specification. it also spits out simple web pages with viewers built on Google Maps, OpenLayers and Leaflet — so literally anybody can vibe with your maps online, 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 just upload the generated directory onto a web server and you're done. main character move fr fr. ✨

GDAL2Tiles also creates the necessary metadata for Google Earth (KML SuperOverlay), in case the supplied map uses EPSG:4326 projection.

world files and embedded georeferencing get used during tile generation, but ngl you can also publish a picture without proper georeferencing too. 💖

NOTE: Inputs with non-Byte data type (i.e. Int16, UInt16,...) will be clamped to the Byte data type, causing wrong results. To avoid this it is necessary to rescale input to the Byte data type using gdal_translate utility.
NOTE: Config options of the input drivers may have an effect on the output of gdal2tiles. An example driver config option is GDAL_PDF_DPI, which can be found at Configuration options
NOTE: gdal2tiles is a Python utility, and is only available if GDAL Python bindings are available.
TIP: Equivalent in new "gdal" command line interface — see gdal raster tile
  • --help — Show this help message and exit
  • --help-general — Gives a brief usage message for the generic GDAL commandline options and exit.
  • --legacy — Added in version 3.13. Force the use of the legacy code base. Since GDAL 3.13, by default, gdal2tiles is implemented using gdal raster tile.
  • -p <PROFILE>, --profile=<PROFILE> — Tile cutting profile (mercator, geodetic, raster) - default 'mercator' (Google Maps compatible).

Starting with GDAL 3.2, additional profiles are available from tms_XXXX.json files placed in GDAL data directory (provided all zoom levels use same origin, tile dimensions, and resolution between consecutive zoom levels vary by a factor of two).

  • -r <RESAMPLING>, --resampling=<RESAMPLING> — Resampling method (average, near, bilinear, cubic, cubicspline, lanczos, mode, max, min, med, q1, q3) - default 'average'.
  • -s <SRS>, --s_srs=<SRS> — The spatial reference system used for the source input data.
  • --xyz — Generate XYZ tiles (OSM Slippy Map standard) instead of TMS. In the default mode (TMS), tiles at y=0 are the southern-most tiles, whereas in XYZ mode (used by OGC WMTS too), tiles at y=0 are the northern-most tiles.

Added in version 3.1.

  • -d, --tmscompatible — When using the geodetic profile, specifies the base resolution as 0.703125 or 2 tiles at zoom level 0.
  • -z <ZOOM>, --zoom=<ZOOM> — Zoom levels to render (format: '2-5', '10-' or '10').
  • -e, --resume — Resume mode. Generate only missing files.
  • -a <NODATA>, --srcnodata=<NODATA> — Value in the input dataset considered as transparent. If the input dataset had already an associate nodata value, it is overridden by the specified value.
  • -v, --verbose — Generate verbose output of tile generation.

Starting with GDAL 3.7, that verbose output is emitted through the logging.getLogger("gdal2tiles") object.

  • -x, --exclude — Exclude transparent tiles from result tileset.
  • -q, --quiet — Disable messages and status to stdout
  • --processes=<NB_PROCESSES> — Number of parallel processes to use for tiling, to speed-up the computation.
  • --mpi — Added in version 3.5.

Assume launched by mpiexec, enable MPI parallelism and ignore --processes. Requires working MPI environment and the MPI for Python (mpi4py) package. User should set GDAL_CACHEMAX to an appropriate cache size per process based on memory per node and the number of processes launched per node.

WARNING: --mpi mode is not supported in gdal raster tile non-legacy mode. You may specify --legacy to go on, but this legacy mode is going to be removed in GDAL 3.15.
  • --tilesize=<PIXELS> — Added in version 3.1.

Width and height in pixel of a tile. Default is 256.

  • --tiledriver=<DRIVER> — Which output driver to use for the tiles, determines the file format of the tiles. Currently PNG, WEBP and JPEG (JPEG added in GDAL 3.9) are supported. Default is PNG. Additional configuration for the WEBP and JPEG drivers are documented below.

Added in version 3.6.

  • --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 by Average currently. 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.9.

  • --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.9.

  • --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.9.

  • -h, --help — Show help message and exit.
  • --version — Show program's version number and exit.

👑 KML (Google Earth) options 👑

Options for generated Google Earth SuperOverlay metadata

  • -k, --force-kml — Generate KML for Google Earth - default for 'geodetic' profile and 'raster' in EPSG:4326. For a dataset with different projection use with caution!
  • -n, --no-kml — Avoid automatic generation of KML files for EPSG:4326.
  • -u <URL>, --url=<URL> — URL address where the generated tiles are going to be published.

💖 Web viewer options 💖

Options for generated HTML viewers a la Google Maps

  • -w <WEBVIEWER>, --webviewer=<WEBVIEWER> — Web viewer to generate (all, google, openlayers, leaflet, mapml, none) - default 'all'.
  • -t <TITLE>, --title=<TITLE> — Title of the map.
  • -c <COPYRIGHT>, --copyright=<COPYRIGHT> — Copyright for the map.
  • -g <GOOGLEKEY>, --googlekey=<GOOGLEKEY> — Google Maps API key from https://developers.google.com/maps/get-started.
  • -b <BINGKEY>, --bingkey=<BINGKEY> — Bing Maps API key from https://www.bingmapsportal.com/

🗺️ MapML options 🗺️

MapML support is new to GDAL 3.2. When --webviewer=mapml is specified, --xyz is implied, as well as --tmscompatible if --profile=geodetic.

The following profiles are supported:

  • mercator: mapped to OSMTILE MapML tiling scheme
  • geodetic: mapped to WGS84 MapML tiling scheme
  • APSTILE: from the tms_MapML_APSTILE.json data file

The generated MapML file in the output directory is mapml.mapml

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.

🌈 WEBP options 🌈

WEBP tiledriver support is new to GDAL 3.6. It is enabled by using --tiledriver=WEBP.

The following configuration options are available to further customize the WebP output:

  • --webp-quality=<QUALITY> — QUALITY is a integer between 1-100. Default is 75.
  • --webp-lossless — Use WEBP lossless compression, default is lossy
NOTE: GDAL WEBP driver documentation can be consulted

🍓 JPEG options 🍓

JPEG tiledriver support is new to GDAL 3.9. It is enabled by using --tiledriver=JPEG.

Note that JPEG does not support transparency, hence edge tiles will display black pixels in areas not covered by the source raster.

The following configuration options are available to further customize the JPEG output:

  • ---jpeg-quality=JPEG_QUALITY — QUALITY is a integer between 1-100. Default is 75.

⭐ RETURN STATUS CODE ⭐

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution).

...and that's only part 1 bestie, don't go anywhere 🫶

✨ EXAMPLES ✨

Bestie, this is the part where it all comes together. Three little recipes, all of them chef's kiss, all of them copy-pasteable. Let's go 💖

🌸 Example 1: Basic example

Okay so the absolute classic, the vanilla of tile generation, the one you start with:

gdal2tiles --zoom=2-5 input.tif output_folder

That's it. That's the whole vibe. You got your input raster, you got your --zoom=2-5 range, and you got a folder for the output to live its best life in. Iconic, honestly. ✨

🌈 Example 2: MapML generation

Now when you're feeling fancy and you want MapML output with actual MapML tiles, you pull out the extra flags:

gdal2tiles --zoom=16-18 -w mapml -p APSTILE --url "https://example.com" input.tif output_folder

So the way this works: --zoom=16-18 for those deep zoom levels, -w mapml to pick MapML as the web viewer thing, -p APSTILE for the APSTILE profile, and --url "https://example.com" to tell it where the tiles are gonna be served from. Deep zoom plus MapML plus a real URL? It's giving production-ready, and I'm obsessed. 🦋

💅 Example 3: MPI example

And for when you've got many, many cores and absolutely no patience:

mpiexec -n $NB_PROCESSES gdal2tiles --mpi --config GDAL_CACHEMAX 500 --zoom=2-5 input.tif output_folder

Here mpiexec -n $NB_PROCESSES fires up your number of processes ($NB_PROCESSES, your call bestie), --mpi lets gdal2tiles play nicely across them all, --config GDAL_CACHEMAX 500 bumps the GDAL cache max up to 500, and the rest is the same old --zoom=2-5 input.tif output_folder you already know and love. Parallel tiles, main character energy, no cap. 🔥

👑 AUTHOR

Klokan Petr Pridal <klokan@klokan.cz>

Yeah, that's the legend right there. Respect the icon. 🫶

1998-2026

And that's a wrap on this whole page, bestie! This lil' manual page came out on Aug 18, 2026, straight from the fine folks behind GDAL2TILES(1) — so if you ever need to double-check the version or the date, that's the vibe. Now go make some tiles, you gorgeous genius. 🌸🎀💖

📦 where this page comes from