GDAL2TILES(1)

💅 gdal2tiles — welcome to the GDAL2TILES(1) page, bestie 💅

okay so this is the manual for gdal2tiles, and it is lowkey iconic. Let’s get into it. 🫶

🌸 NAME 🌸

gdal2tiles — Generates directory with TMS tiles, KMLs and simple web viewers. That’s the whole assignment. ✨

🦋 SYNOPSIS 🦋

Here’s the shape of the command, no cap:

   gdal2tiles.py [-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] [--xyz]
                 --tilesize=PIXELS
                 [-g googlekey] [-b bingkey] input_file [output_dir] [COMMON_OPTIONS]

✨ DESCRIPTION ✨

Okay so this utility generates a directory with small tiles and metadata, following the OSGeo Tile Map Service Specification. Simple web pages with viewers based on Google Maps, 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. Slay. 💖

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 is used during tile generation, but you can publish a picture without proper georeferencing too. The range! 🌈

⚠️ 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. Do not skip this, fr fr. 😭

⚠️ 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 configoptions. iykyk. 💀

🌟 OPTIONS 🌟

• -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, antialias, mode, max, min, med, q1, q3) — default 'average'. Pick your fighter. 🥊
• -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. ✨ New in version 3.1.
• -z <ZOOM>, --zoom=<ZOOM> — Zoom levels to render (format: '2-5', '10-' or '10'). 🎚️
• -e, --resume — Resume mode. Generate only missing files. Efficient queen behavior.
• -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.
• -x, --exclude — Exclude transparent tiles from result tileset.
• -q, --quiet — Disable messages and status to stdout. ✨ New in version 2.1.
• --processes=<NB_PROCESSES> — Number of parallel processes to use for tiling, to speed-up the computation. ✨ New in version 2.3.
• --tilesize=<PIXELS> — Width and height in pixel of a tile. Default is 256. ✨ New in version 3.1.
• -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. Cute, right? 🌍

• -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. Very main character. 💅

• -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 http://code.google.com/apis/maps/signup.html.
• -b <BINGKEY>, --bingkey=<BINGKEY> — Bing Maps API key from https://www.bingmapsportal.com/.

🐍 NOTE: gdal2tiles.py is a Python script that needs to be run against Python GDAL binding. Okurrr.

🗺️ 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 way that combo just clicks. ✨

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.mapl. Not a typo, bestie. 🎀

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 🔥

Basic example:

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

MapML generation:

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

👑 AUTHOR 👑

Klokan Petr Pridal <klokan@klokan.cz> — icon behavior. 💖

💜 COPYRIGHT 💜

1998-2026

---

That’s the GDAL2TILES(1) manual, source/version GDAL, dated Jan 08, 2026. Byeee bestie, go tile something iconic! 🫶💖🎀