GDAL_TRANSLATE(1)

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

✨ NAME ✨

gdal_translate — bestie, this is the GDAL tool that converts raster data between different formats. That's it. That's the whole job. 💅

🌸 SYNOPSIS 🌸

Usage: gdal_translate [--help] [--long-usage] [--help-general]
                      [-ot Byte|Int8|[U]Int{16|32|64}|CInt{16|32}|[C]Float{32|64}]
                      [-if <format>]... [-of <output_format>] [--quiet]
                      [-b <band>]... [-mask <mask>] [-expand gray|rgb|rgba]
                      [[-strict]|[-not_strict]]
                      [-outsize <xsize[%]|0> <ysize[%]|0>] [-tr <xres> <yres>]
                      [-ovr <level>|AUTO|AUTO-<n>|NONE] [-sds]
                      [-r nearest,bilinear,cubic,cubicspline,lanczos,average,mode]
                      [[-scale [<src_min> <src_max> [<dst_min> <dst_max>]]]...|
                      [-scale_X [<src_min> <src_max> [<dst_min> <dst_max>]]]...|
                      [-unscale]]
                      [[-exponent <value>]|[-exponent_X <value>]...]
                      [-srcwin <xoff> <yoff> <xsize> <ysize>]
                      [-projwin <ulx> <uly> <lrx> <lry>]
                      [-projwin_srs <srs_def>] [-epo] [-eco] [-a_srs <srs_def>]
                      [-a_coord_epoch <epoch>] [-a_ullr <ulx> <uly> <lrx> <lry>]
                      [-a_nodata <value>|none]
                      [-a_gt <gt(0)> <gt(1)> <gt(2)> <gt(3)> <gt(4)> <gt(5)>]
                      [-a_scale <value>] [-a_offset <value>] [-nogcp]
                      [-gcp <pixel> <line> <easting> <northing> [<elevation>]]...
                      [-colorinterp {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...},...]
                      [-colorinterp_X {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...}]...
                      [[-stats]|[-approx_stats]]
                      [-norat] [-noxmp] [-co <NAME>=<VALUE>]...
                      [-mo <NAME>=<VALUE>]... [-dmo <DOMAIN>:<KEY>=<VALUE>]...
                      [-oo <NAME>=<VALUE>]...
                      <input_file> <output_file>

💖 DESCRIPTION 💖

okay so the gdal_translate utility is your girl for converting raster data between different formats, and while she's at it she can also do a whole bunch of glow-up operations on the pixels — like subsetting, resampling, and rescaling. multi-talented. she ate. 🔥

TIP bestie: there's an equivalent in the new gdal command line interface, if that's more your vibe: - gdal raster convert for format translation. - gdal raster clip for spatial subsetting. - gdal raster nodata-to-alpha to add an alpha channel from nodata values. - gdal raster resize for image resizing. - gdal raster scale to scale pixel values. - gdal raster set-type to change the band data type.

🎀 the flags, one by one, no skipping 🎀

  • --help — Show this help message and exit. That's it. bye. 👋
  • --help-general — Gives you a brief usage message for the generic GDAL commandline options, and then it exits.
  • -q, --quiet — Suppress progress messages and other non-error output. shhh 🤫
  • -ot <type> — Force the output image bands to have a specific data type supported by the driver. it can be one of these, and only these: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.
  • -strict — Enable strict mode. bestie, in this mode GDAL will fail instead of quietly doing operations that might lose information — like data type conversions that can't be exactly preserved. no sneaky lossy behaviour allowed, periodt.

The exact behavior of this option is driver-dependent. Most raster drivers use it to enforce strict preservation of the input data type and will report an error if the requested operation cannot be performed without data loss. See Example 5. 👀

  • -if <format> — Format/driver name to be attempted to open the input file(s). You generally don't need to specify it, but it's a lifesaver when automatic driver detection fails to pick the right driver. You can repeat this option several times to hand over several candidate drivers. ⚠️ Just knowing: it does not force those drivers to open the dataset. And heads up — some drivers have requirements on file extensions.

Added in version 3.2.

  • -of <format> — Select the output format. If you don't specify it, the format gets guessed from the extension. Use the short format name. ✨
  • -b <band> — Select an input band for output. Bands are numbered from 1. Multiple -b switches can be used to select a set of input bands to write to the output file, or to reorder bands. band can also be set to "mask,1" (or just "mask") to mean the mask band of the first band of the input dataset. 🦋
  • -mask <band> — Select an input band to create the output dataset mask band. Bands are numbered from 1. band can be set to "none" to avoid copying the global mask of the input dataset if it exists. Otherwise it is copied by default ("auto"), unless the mask is an alpha channel, or if it is explicitly used to be a regular band of the output dataset (-b mask). band can also be set to "mask,1" (or just "mask") to mean the mask band of the 1st band of the input dataset.
  • -expand gray|rgb|rgba — To expose a dataset with 1 band with a color table as a dataset with 3 (RGB) or 4 (RGBA) bands. Super useful for output drivers like JPEG, JPEG2000, MrSID, ECW that don't support color indexed datasets. The gray value enables you to expand a dataset with a color table that only contains gray levels to a gray indexed dataset. 🎨
  • -outsize <xsize>[%]|0 <ysize>[%]|0 — Set the size of the output file. Outsize is in pixels and lines, unless % is attached — in which case it's a fraction of the input image size. If one of the 2 values is set to 0, its value will be determined from the other one, while maintaining the aspect ratio of the source dataset. 📐
  • -tr <xres> <yres> — Set target resolution. The values must be expressed in georeferenced units. Both must be positive values. This is mutually exclusive with -outsize, -a_ullr, and -a_gt. pick a lane bestie.
  • -ovr {<level>|AUTO|AUTO-<n>|NONE} — To specify which overview level of the source file must be used. Added in version 3.6.

The default choice, AUTO, will select the overview level whose resolution is the closest to the target resolution. Specify an integer value (0-based, i.e. 0 = 1st overview level) to select a particular level. Specify AUTO-n where n is an integer greater or equal to 1, to select an overview level below the AUTO one. Or specify NONE to force the base resolution to be used — which can be useful if overviews have been generated with a low quality resampling method, and a higher quality resampling method is specified with -r. 💅

When -ovr is specified as an integer value, and neither -outsize nor -tr is specified, the size of the overview will be used as the output size.

When -ovr is specified, values of -srcwin should be expressed as pixel offset and size of the full resolution source dataset. Similarly, when using -outsize with percentage values, they refer to the size of the full resolution source dataset.

  • -r {nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode} — Select a resampling algorithm. here's the roster, queen by queen:
    • nearest (default) applies a nearest neighbour (simple sampling) resampler
    • average computes the average of all non-NODATA contributing pixels. Starting with GDAL 3.1, this is a weighted average taking into account properly the weight of source pixels not contributing fully to the target pixel.
    • rms computes the root mean squared / quadratic mean of all non-NODATA contributing pixels (GDAL >= 3.3)
    • bilinear applies a bilinear convolution kernel.
    • cubic applies a cubic convolution kernel.
    • cubicspline applies a B-Spline convolution kernel.
    • lanczos applies a Lanczos windowed sinc convolution kernel.
    • mode selects the value which appears most often of all the sampled points.
  • -scale [<src_min> <src_max> [<dst_min> <dst_max>]] — Rescale the input pixels values from the range src_min to src_max to the range dst_min to dst_max. If omitted, the output range is from the minimum value to the maximum value allowed for integer data types (for example from 0 to 255 for Byte output) or from 0 to 1 for floating-point data types. If omitted, the input range is automatically computed from the source dataset, in its whole — not just the window of interest potentially specified with -srcwin or -projwin. This may be a slow operation on a large source dataset, and if you're using it multiple times for several gdal_translate invocation, it might be beneficial to call gdalinfo -stats {source_dataset} priorly to precompute statistics, for formats that support serializing statistics computations (GeoTIFF, VRT...). 🐢
Note bestie: the values specified after -scale are only used to compute a scale and offset to apply to the input raster values. In particular, src_min and src_max are not used to clip input values unless -exponent is also specified. Instead of being clipped, source values that are outside the range of src_min and src_max will be scaled to values outside the range of dst_min and dst_max. If clipping without exponential scaling is desired, -exponent 1 can be used.

-scale can be repeated several times (if specified only once, it also applies to all bands of the output dataset), so as to specify per band parameters. It is also possible to use the -scale_bn syntax where bn is a band number (e.g. -scale_2 for the 2nd band of the output dataset) to specify the parameters of one or several specific bands. 🫶

  • -exponent <exp_val> — Apply non-linear scaling with a power function. exp_val is the exponent of the power function (must be positive). This option must be used with the -scale option. If specified only once, -exponent applies to all bands of the output image. It can be repeated several times so as to specify per band parameters. It is also possible to use the -exponent_bn syntax where bn is a band number (e.g. -exponent_2 for the 2nd band of the output dataset) to specify the parameters of one or several specific bands. 💫

...and the scaled value Dst comes out of the source value Src with this whole formula, slay:

{Dst} = \left( {Dst}_{max} - {Dst}_{min} \right) \times \operatorname{max} \left( 0, \operatorname{min} \left( 1, \left( \frac{{Src} - {Src}_{min}}{{Src}_{max}-{Src}_{min}} \right)^{exp\_val} \right) \right) + {Dst}_{min}

Like, it's giving math but make it fashion 💅 don't worry about it, the computer handles it.

  • -unscale — bestie, this one grabs the scale/offset metadata on the bands and does the reverse move: turns linearly-scaled values back into unscaled ones. You'll usually need to reset the output datatype with the -ot switch too, just saying. 🙈 Here's how the unscaled value gets computed from the scaled raw value:
{unscaled\_value} = {scaled\_value} * {scale} + {offset}
  • -srcwin <xoff> <yoff> <xsize> <ysize> — picks a subwindow out of the source image to copy, using pixel/line location. The pixel/line offsets (xoff and yoff) are measured from the left and top of the image. If that subwindow goes past the bounds of the source dataset, the output pixels get written with a value of zero — unless a NoData value is defined, either in the source dataset or via -a_nodata. OR, if you want, gdal_translate can throw an error in that case if you direct it with -epo or -eco. Your call, main character. ✨
  • -projwin <ulx> <uly> <lrx> <lry> — same energy as -srcwin, picks a subwindow from the source image for copying, but the corners are given in georeferenced coordinates (by default expressed in the SRS of the dataset — you can change that with -projwin_srs). If the subwindow extends beyond the bounds of the source dataset, output pixels get written with a value of zero, unless a NoData value is defined either in the source dataset or by -a_nodata. Alternatively, gdal_translate can issue an error here too if -epo or -eco tells it to.
NOTE: Starting with GDAL 3.11, the extent described by -projwin will be transformed into the dataset SRS and used to select a subwindow. Before GDAL 3.11, only the two corner points were transformed into the dataset SRS, and those two transformed points were used to define an extent in the dataset SRS. Depending on the SRS involved, the subwindow selected in GDAL 3.11 may be substantially larger than in previous versions. 😭
NOTE: When you're using nearest-neighbor resampling, the window specified by -projwin gets expanded (rounded, for GDAL < 3.11) if needed to match input pixel boundaries. For other resampling algorithms, the window is not modified. periodt.
  • -projwin_srs <srs_def> — says which SRS to interpret the coordinates given with -projwin in. The <srs_def> can be any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n, or a file containing the WKT.
WARNING: This does not cause reprojection of the dataset to the specified SRS. it's giving "just a label" energy, do not be fooled bestie 💀
  • -epo — (Error when Partially Outside) if you set this, -srcwin or -projwin values that fall partially outside the source raster extent get treated as an error. The default behavior is to just accept those requests.
  • -eco — (Error when Completely Outside) same as -epo, except the criterion for erroring out is when the request falls completely outside the source raster extent.
  • -a_srs <srs_def> — overrides the projection for the output file. Can be used with -a_ullr or -a_gt to specify the extent in this projection.

The coordinate reference systems you can pass are anything supported by the OGRSpatialReference::SetFromUserInput() call, which includes EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition. so many options, we love a flexible queen 🌈

NOTE: No reprojection is done. 🫶
  • -a_coord_epoch <epoch> — added in version 3.4. Assigns a coordinate epoch, linked with the output SRS. Super useful when the output SRS is a dynamic CRS. 🦋
  • -a_scale <value> — sets the band scaling value. No modification of pixel values is done, ngl. Note that -unscale does not take -a_scale into account. You may for example specify -scale 0 1 <offset> <offset+scale> to apply a (offset, scale) tuple, for the equivalent of the 2 steps:
gdal_translate input.tif tmp.vrt -a_scale scale -a_offset offset

followed by:

gdal_translate tmp.vrt output.tif -unscale
  • -a_offset <value> — sets the band offset value. No modification of pixel values is done. Note that -unscale does not take -a_offset into account. You may for example specify -scale 0 1 <offset> <offset+scale> to apply a (offset, scale) tuple, for the equivalent of the 2 steps:
gdal_translate input.tif tmp.vrt -a_scale scale -a_offset offset

followed by:

gdal_translate tmp.vrt output.tif -unscale
  • -a_ullr <ulx> <uly> <lrx> <lry> — assigns/overrides the georeferenced bounds of the output file. This assigns georeferenced bounds to the output file, ignoring what would have been derived from the source file. So this does not cause reprojection to the specified SRS. This is mutually exclusive with -a_gt. 💅
  • -a_gt <gt(0)> <gt(1)> <gt(2)> <gt(3)> <gt(4)> <gt(5)> — assigns/overrides the geotransform of the output file. This assigns the geotransform to the output file, ignoring what would have been derived from the source file. So this does not cause reprojection to the specified SRS. See Geotransform Tutorial. This is mutually exclusive with -a_ullr.

Added in version 3.8. ✨

  • -a_nodata <value> — assigns a specified nodata value to the output bands. It can be set to none to avoid setting a nodata value on the output file if one exists for the source file. Note that, if the input dataset already has a nodata value, this does not cause pixel values that are equal to that nodata value to be changed to the value you specified with this option. important plot twist bestie 😭
  • -colorinterp_X <red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...> — overrides the color interpretation of band X (where X is a valid band number, starting at 1). ✨
  • -colorinterp {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...},... — overrides the color interpretation of all the specified bands. For example -colorinterp red,green,blue,alpha for a 4 band output dataset. go off 👑
  • -mo <META-TAG>=<VALUE> — passes a metadata key and value to set on the output dataset if possible.
  • -dmo DOMAIN:META-TAG=VALUE — passes a metadata key and value in the specified domain to set on the output dataset if possible.

Added in version 3.9. 🎀

  • -co <NAME>=<VALUE> — ok so many formats have one or more optional creation options that you can use 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. You can list the options a format supports with the --format command line option, but the documentation for the format is the definitive source of info on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.

On top of the driver-specific creation options, gdal_translate (and GDALTranslate() and GDALCreateCopy()) recognize these:

  • APPEND_SUBDATASET=[YES/NO]: defaults to NO.

Can be specified as YES to avoid prior destruction of the existing dataset, for drivers that support adding several subdatasets (e.g. GTIFF, NITF).

  • COPY_SRC_MDD=[AUTO/YES/NO]: (GDAL >= 3.8) defaults to AUTO.

Defines if metadata domains of the source dataset should be copied to the destination dataset. In the default AUTO mode, only "safe" domains will be copied, which include the default metadata domain (some drivers may include other domains such as IMD, RPC, GEOLOCATION). When setting YES, all domains will be copied (but a few reserved ones like IMAGE_STRUCTURE or DERIVED_SUBDATASETS). Currently only recognized by the GTiff, COG, VRT, PNG and JPEG drivers.

When setting NO, no source metadata will be copied. 🫶

  • SRC_MDD=<domain_name>: (GDAL >= 3.8)

Defines which source metadata domain should be copied. This option restricts the list of source metadata domains to be copied (it implies COPY_SRC_MDD=YES if it is not set). This option may be specified as many times as they are source domains. The default metadata domain is the empty string "" ("_DEFAULT_" may also be used when empty string is not practical). Currently only recognized by the GTiff, COG, VRT, PNG and JPEG drivers. 💜

  • -nogcp — do not copy the GCPs in the source dataset to the output dataset.
  • -gcp <pixel> <line> <easting> <northing> [<elevation>] — add the indicated ground control point to the output dataset. This option may be provided multiple times to provide a set of GCPs. stack 'em up bestie 🌸
  • -q — suppresses the progress monitor and other non-error output. quiet luxury vibes 🤫
  • -sds — copies all subdatasets of this file to individual output files. Use with formats like HDF that have subdatasets.
  • -stats — force (re)computation of statistics.
  • -norat — do not copy source RAT into destination dataset.
  • -noxmp — do not copy the XMP metadata in the source dataset to the output dataset when the driver is able to copy it.

Added in version 3.2. ✨

  • -oo <NAME>=<VALUE> — dataset open option (format specific).
  • <src_dataset> — the source dataset name. It can be either a file name, URL of data source, or subdataset name for multi-dataset files. 🦋
  • <dst_dataset> — the destination file name.

✨ NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING ✨

okay bestie this one is important so like, listen up 💖 Masked values — that's stuff identified through a nodata value metadata set on the source band, or a mask band, or an alpha band — those will not be used during resampling (and this kicks in whenever you're using -outsize or -tr). Periodt.

How exactly that gets taken into account lowkey depends on the resampling kernel you picked. So:

  • for nearest resampling, for each target pixel, one of the potential contributing source pixels is selected (in an implementation specific way, so like, don't ask which one 💀). Its value is used as is, be it valid or invalid. No arguments, she's committed.
  • for bilinear, cubic, cubicspline and lanczos, for each target pixel, the weights of contributing source pixels are set to zero so they get ignored when they're masked. But there's an extra specificity for cubic and lanczos: given that some of the weights in the kernel are negative 😭 such strategy could lead to strong overshoot/undershoot when there's an alternance of valid and invalid pixels. So consequently, if any of the horizontal or vertical direction, if the maximum number of valid source pixels in each dimension is less than the radius of the resampling kernel, the target pixel is considered as nodata. She said nope, not doing it, marking it nodata 💅
  • for the other resampling methods, source pixels contributing to the target pixel are ignored if masked. Only the valid ones get taken into account. And if there are none? Yeah the target pixel is considered as nodata. Nothing to work with, nothing to output 🌸

✨ RETURN STATUS CODE ✨

The program returns status code 0 in case of success, and non-zero in case of error. And yes, non-blocking errors emitted as warnings are considered as a successful execution — so don't panic if you see a little warning, bestie, she's fine 🫶

✨ C API ✨

Not me telling you this is also callable from C 👑 This utility is also callable from C with GDALTranslate().

✨ EXAMPLES ✨

Real ones only, let's go 🌈

🌸 Example 1: Creating a tiled GeoTIFF

gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif

🌸 Example 2: Creating a JPEG-compressed TIFF with internal mask from a RGBA dataset

gdal_translate rgba.tif withmask.tif -b 1 -b 2 -b 3 -mask 4 -co COMPRESS=JPEG \
  -co PHOTOMETRIC=YCBCR --config GDAL_TIFF_INTERNAL_MASK YES

🌸 Example 3: Creating a RGBA dataset from a RGB dataset with a mask

gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask

🌸 Example 4: Subsetting using -projwin and -outsize

gdal_translate -projwin -20037500 10037500 0 0 -outsize 100 100 frmt_wms_googlemaps_tms.xml junk.png

🌸 Example 5: Use of strict mode with unsupported data type

$ gdal_create test.tif -bands 3 -ot Int16 -outsize 1 1
$ gdal_translate -strict test.tif test.webp
ERROR 6: WEBP driver doesn't support data type Int16.
Only UInt8 bands supported.
not the driver straight up rejecting Int16 😭 strict mode said "no ma'am, we're not doing that today"

💜 AUTHOR 💜

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>

Absolute icons, we stan 🎀

1998-2026

and that's a wrap bestie 💖 this page is from the GDAL docs, dated Aug 18, 2026, and it's GDAL_TRANSLATE(1) — go translate something gorgeous 🦋✨

📦 where this page comes from