GDALWARP(1)

📦
version 3.4.3 · 2 versions
, in epel 9

👑 GDALWARP(1) 👑

okay so real talk — this is the GDAL manual page, and today's episode is all about the one, the only, gdalwarp. grab a snack, bestie, this one's a whole journey 🍓

💖 NAME 💖

gdalwarp — the image reprojection and warping utility. that's it. that's the whole vibe. ✨

🦋 SYNOPSIS 🦋

   gdalwarp [--help-general] [--formats]
       [-s_srs srs_def] [-t_srs srs_def] [-ct string] [-to "NAME=VALUE"]* [-vshift | -novshift]
       [[-s_coord_epoch epoch] | [-t_coord_epoch epoch]]
       [-order n | -tps | -rpc | -geoloc] [-et err_threshold]
       [-refine_gcps tolerance [minimum_gcps]]
       [-te xmin ymin xmax ymax] [-te_srs srs_def]
       [-tr xres yres] [-tap] [-ts width height]
       [-ovr level|AUTO|AUTO-n|NONE] [-wo "NAME=VALUE"] [-ot Byte/Int16/...] [-wt Byte/Int16]
       [-srcnodata "value [value...]"] [-dstnodata "value [value...]"]
       [-srcalpha|-nosrcalpha] [-dstalpha]
       [-r resampling_method] [-wm memory_in_mb] [-multi] [-q]
       [-cutline datasource] [-cl layer] [-cwhere expression]
       [-csql statement] [-cblend dist_in_pixels] [-crop_to_cutline]
       [-if format]* [-of format] [-co "NAME=VALUE"]* [-overwrite]
       [-nomd] [-cvmd meta_conflict_value] [-setci] [-oo NAME=VALUE]*
       [-doo NAME=VALUE]*
       srcfile* dstfile

like, yes, that's a lot of brackets. breathe. we'll get through it together 🫶

🌸 DESCRIPTION 🌸

so what does gdalwarp actually do? it's an image mosaicing, reprojection and warping utility. iconic behaviour, honestly.

the program can reproject to any supported projection, and it can also apply GCPs stored with the image — but only if the image is "raw" and has control information. that's the catch, bestie 💅

✨ the options ✨

okay buckle up, this is the main character section 👑

  • -s_srs <srs def> — sets the source spatial reference. if you don't specify it, the SRS that's already chillin' in the input dataset gets used instead. no drama.

the coordinate reference systems you can pass are literally anything supported by the OGRSpatialReference.SetFromUserInput() call, and that 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.

and starting with GDAL 2.2: if the SRS has an explicit vertical datum that points to a PROJ.4 geoidgrids, and the input dataset is a single band dataset, a vertical correction will be applied to the values of the dataset. little glow-up for your data ✨

  • -s_coord_epoch <epoch> — New in version 3.4. assigns a coordinate epoch, linked with the source SRS. super useful when the source SRS is a dynamic CRS. only taken into account if -s_srs is used, so don't be out here using it solo 🙈
⚠️ heads up: currently -s_coord_epoch and -t_coord_epoch are mutually exclusive, because there's no support for transformations between two dynamic CRS. it's giving "we don't do that here" 😭
  • -t_srs <srs_def> — sets the target spatial reference. quick note: a source SRS must be available for reprojection to actually happen. the source SRS will be, by default, the one found in the input dataset when it's available — or as overridden by you with -s_srs.

same deal as before: the CRSs 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.

and again, starting with GDAL 2.2: if the SRS has an explicit vertical datum that points to a PROJ.4 geoidgrids, and the input dataset is a single band dataset, a vertical correction gets applied to the values of the dataset. slay 🌈

  • -t_coord_epoch <epoch> — New in version 3.4. assigns a coordinate epoch, linked with the target SRS. useful when the target SRS is a dynamic CRS. only taken into account if -t_srs is used.
⚠️ and yeah, same warning as its sibling: -s_coord_epoch and -t_coord_epoch are currently mutually exclusive — lack of support for transformations between two dynamic CRS. periodt 💀
  • -ct <string> — a PROJ string (single step operation or multiple step string starting with +proj=pipeline), a WKT2 string describing a CoordinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX URN that overrides the default transformation from the source to the target CRS. it must take into account the axis order of the source and target CRS — no skipping that part, bestie.

New in version 3.0.

  • -to <NAME=VALUE> — set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2(). very "here's a little something extra" energy 🎀
  • -vshift — force the use of vertical shift. honestly this one is generally not necessary, except when you're using an explicit coordinate transformation (-ct) and not specifying an explicit source and target SRS.

New in version 3.4.

  • -novshift — disables the use of vertical shift when one of the source or target SRS has an explicit vertical datum, and the input dataset is a single band dataset.
📌 NOTE: this option was named -novshiftgrid in GDAL 2.2 to 3.3. so if you're on an older version and confused, that's why, iykyk 🙈

New in version 3.4.

  • -order <n> — the order of polynomial used for warping, 1 to 3. the default is to select a polynomial order based on the number of GCPs. it just knows ✨
  • -tps — force use of thin plate spline transformer based on available GCPs.
  • -rpc — force use of RPCs.
  • -geoloc — force use of Geolocation Arrays.
  • -et <err_threshold> — error threshold for transformation approximation, in pixel units. defaults to 0.125 — unless, starting with GDAL 2.1, the RPC_DEM warping option is specified, in which case an exact transformer, i.e. err_threshold=0, will be used. surprise upgrade 🔥
  • -refine_gcps <tolerance minimum_gcps> — refines the GCPs by automatically eliminating outliers. outliers get eliminated until minimum_gcps are left, or until no outliers can be detected. the tolerance is passed to adjust when a GCP will be eliminated. note that GCP refinement only works with polynomial interpolation. the tolerance is in pixel units if no projection is available, otherwise it's in SRS units. and if minimum_gcps isn't provided, the minimum GCPs according to the polynomial model is used.
  • -te <xmin ymin xmax ymax> — set the georeferenced extents of the output file to be created. that's in the target SRS by default, or in the SRS you specified with -te_srs.
  • -te_srs <srs_def> — specifies which SRS to interpret the coordinates given with -te in. the <srs_def> may be any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n, or a file containing the WKT.
🚨 do not confuse this with -t_srs, which is the target SRS of the output dataset. -te_srs is just a convenience — e.g. when you know the output coordinates in a geodetic long/lat SRS but still want a result in a projected coordinate system. different girl, different job 💅
  • -tr <xres> <yres> — set the output file resolution, in target georeferenced units.

if it's not specified (or not deduced from -te and -ts), gdalwarp will generate an output raster with xres=yres — and that's true even when you're using gdalwarp in scenarios that don't involve reprojection at all. consistency queen 🌸

  • -tap — (target aligned pixels) aligns the coordinates of the extent of the output file to the values of -tr, such that the aligned extent includes the minimum extent. snug fit, no gaps 🎀
  • -ts <width> <height> — set the output file size in pixels and lines. if width or height is set to 0, the other dimension will be guessed from the computed resolution. note that -ts cannot be used with -tr. pick a lane bestie 😭
  • -ovr <level|AUTO|AUTO-n|NONE> — lets you specify which overview level of the source files must be used.
    • 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 than or equal to 1, to select an overview level below the AUTO one.
    • or specify NONE to force the base resolution to be used. that one can be useful if overviews were generated with a low quality resampling method, and the warping is being done using a higher quality resampling method. glow-up via brute force 💅
  • -wo "NAME=VALUE" — set a warp option. the GDALWarpOptions::papszWarpOptions docs show all the options, so go peek 👀. multiple -wo options may be listed — stack 'em.
  • -ot <type> — force the output image bands to have a specific data type supported by the driver. which may be one of the following: Byte, UInt16, Int16, UInt32, Int32, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.
  • -wt <type> — working pixel data type. that's the data type of pixels in the source image and destination image buffers. the in-between fit 💜
  • -r <resampling_method> — resampling method to use. available methods are:
    • near: nearest neighbour resampling (default, fastest algorithm, worst interpolation quality). yes, it's the fastest and also the ugliest. we love an honest queen 😭
    • bilinear: bilinear resampling.
    • cubic: cubic resampling.
    • cubicspline: cubic spline resampling.
    • lanczos: Lanczos windowed sinc resampling.
    • average: average resampling, computes the weighted average of all non-NODATA contributing pixels.
    • rms: root mean square / quadratic mean of all non-NODATA contributing pixels (GDAL >= 3.3)
    • mode: mode resampling, selects the value which appears most often of all the sampled points.
    • max: maximum resampling, selects the maximum value from all non-NODATA contributing pixels.
    • min: minimum resampling, selects the minimum value from all non-NODATA contributing pixels.
    • med: median resampling, selects the median value of all non-NODATA contributing pixels.
    • q1: first quartile resampling, selects the first quartile value of all non-NODATA contributing pixels.
    • q3: third quartile resampling, selects the third quartile value of all non-NODATA contributing pixels.
    • sum: compute the weighted sum of all non-NODATA contributing pixels (since GDAL 3.1)
  • -srcnodata <value [value...]> — set nodata masking values for input bands. different values can be supplied for each band 🫶

if more than one value is supplied, all values should be quoted to keep them together as a single operating system argument. masked values will not be used in interpolation. and use a value of None to ignore intrinsic nodata settings on the source dataset.

when this option is set to a non-None value, it causes the UNIFIED_SRC_NODATA warping option (see GDALWarpOptions::papszWarpOptions) to be set to YES, if it isn't explicitly set already. automatic, we love to see it ✨

If -srcnodata isn't explicitly set but your source dataset does have nodata values, bestie, they get taken into account anyway — with UNIFIED_SRC_NODATA at PARTIAL by default. ✨

  • -dstnodata <value [value...]> — sets the nodata value(s) for the output bands (yep, different values per band are allowed 🌈). If you're passing more than one value, quote them all so they stay together as a single OS argument, ok? New files get initialized to this value and, if possible, the nodata value gets written into the output file. Pass a value of None to make sure nodata is not defined. If you don't use this argument at all, nodata values are copied from the source dataset. 💖
  • -srcalpha — forces the last band of a source image to be treated as a source alpha band.
  • -nosrcalpha — stops the alpha band of a source image from being considered as such (so it gets warped as a regular band instead).

New in version 2.2.

  • -dstalpha — creates an output alpha band so you can actually identify the nodata (unset/transparent) pixels. 👑
  • -wm <memory_in_mb> — sets how much memory the warp API is allowed to use for caching. The value counts as megabytes if it's less than 10000; for values >=10000 it's interpreted as bytes. 🧠
  • -multi — use the multithreaded warping implementation. Two threads process chunks of image and do input/output operations at the same time. Note bestie: the computation itself is not multithreaded. Want that too? Use the -wo NUM_THREADS=val/ALL_CPUS option, which you can totally combine with -multi. 🔥
  • -q — be quiet. 🤫
  • -if <format> — format/driver name to be attempted when opening the input file(s). You generally don't need to specify it, but it's there to skip automatic driver detection when that fails to pick the right driver. You can repeat this option several times to give several candidate drivers. 🎀

New in version 3.2.

  • -of <format> — select the output format. Starting with GDAL 2.3, if you don't specify it, the format is guessed from the extension (before that, it was GTiff). Use the short format name, mmkay?
  • -co <NAME=VALUE> — tons of formats have one or more optional creation options that control particulars about the file being created. Like, the GeoTIFF driver has creation options for compression and whether the file should be tiled. The available creation options vary by format driver, and some simple formats have no creation options at all. You can list a format's supported options with the --formats 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 the legal creation options of each format. 💅
  • -cutline <datasource> — enables using a blend cutline from the named OGR-supporting datasource. ✂️
  • -cl <layername> — selects the named layer from the cutline datasource.
  • -cwhere <expression> — restricts the desired cutline features based on an attribute query.
  • -csql <query> — selects cutline features using an SQL query instead of from a layer via -cl.
  • -cblend <distance> — sets a blend distance to blend over cutlines (in pixels). 🦋
  • -crop_to_cutline — crops the extent of the target dataset to the extent of the cutline.
  • -overwrite — overwrites the target dataset if it already exists. And "overwrite" here means deleting and recreating the file from scratch, no cap. Note that if you don't specify this and the output file already exists, it gets updated in place instead. ⚠️
  • -nomd — do not copy metadata. Without this option, dataset and band metadata (plus some band information) gets copied from the first source dataset. Items that differ between source datasets get set to * (see the -cvmd option). 🙈
  • -cvmd <meta_conflict_value> — the value to set for metadata items that conflict between source datasets (default is "*"). Use "" to remove conflicting items entirely.
  • -setci — sets the color interpretation of the target dataset's bands from the source dataset. 🌈
  • -oo <NAME=VALUE> — dataset open option (format specific).
  • -doo <NAME=VALUE> — output dataset open option (format specific).

New in version 2.1.

  • <srcfile> — the source file name(s). 🍓
  • <dstfile> — the destination file name.

Mosaicing into an existing output file is supported if that output file already exists. But heads up: the spatial extent of the existing file will not be modified to accommodate new data, so you might have to remove it in that case — or just use the -overwrite option. 💀

Polygon cutlines can be used as a mask to restrict the area of the destination file that may be updated, blending included. If the OGR layer holding the cutline features has no explicit SRS, then the cutline features must be in the SRS of the destination file. And when you're writing to a not-yet-existing target dataset, its extent will be the one of the original raster unless -te or -crop_to_cutline are specified. 🧚

Starting with GDAL 3.1, you can use a driver that only supports the CreateCopy operation as your output format. This may internally imply creation of a temporary file. ✨

🌸 EXAMPLES 🌸

  • Basic transformation:
gdalwarp -t_srs EPSG:4326 input.tif output.tif
  • For instance, an eight bit spot scene stored in GeoTIFF with control points mapping the corners to lat/long could be warped to a UTM projection with a command like this:
gdalwarp -t_srs '+proj=utm +zone=11 +datum=WGS84' -overwrite raw_spot.tif utm11.tif
  • For instance, the second channel of an ASTER image stored in HDF with control points mapping the corners to lat/long could be warped to a UTM projection with a command like this:

New in version 2.2.

gdalwarp -overwrite HDF4_SDS:ASTER_L1B:"pg-PR1B0000-2002031402_100_001":2 pg-PR1B0000-2002031402_100_001_2.tif
  • To apply a cutline on a un-georeferenced image and clip from pixel (220,60) to pixel (1160,690):
gdalwarp -overwrite -to SRC_METHOD=NO_GEOTRANSFORM -to DST_METHOD=NO_GEOTRANSFORM -te 220 60 1160 690 -cutline cutline.csv in.png out.tif

where cutline.csv content is like:

id,WKT
1,"POLYGON((....))"
  • To transform a DEM from geoid elevations (using EGM96) to WGS84 ellipsoidal heights:

New in version 2.2.

gdalwarp -overwrite in_dem.tif out_dem.tif -s_srs EPSG:4326+5773 -t_srs EPSG:4979

👀 SEE ALSO 👀

Wiki page discussing options and behaviours of gdalwarp — literally go read it, iykyk.

💜 AUTHOR 💜

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de> — legends, honestly. 🫶

1998-2026

And that's the whole page, bestie!! This one's the GDALWARP(1) man page, last touched Jan 08, 2026 — go warp something iconic 💅✨

📦 where this page comes from