raster.rewrite_tiff()

Rewrite a GeoTIFF, optionally to a different storage backend.

Usage

Source

raster.rewrite_tiff(
    src_file,
    dst_file,
    profile=None,
    band_names=None,
    color_interp=None,
    *,
    tags=None,
    band_tags=None,
    units=None,
    move=False
)

Useful for applying compression/tiling, renaming bands, or copying files between local disk and S3, or between two different S3 backends (each side’s credentials are applied independently). Source-side band descriptions, color interpretation, NODATA, and tags are preserved automatically.

The rewrite is always staged (a unique local sibling temp file, or an in-memory image for S3 destinations) and only swapped into place after the full copy and metadata injection succeed. A pre-existing destination is therefore left untouched on any failure, and the source is only deleted when move=True (and never when it fails).

Parameters

src_file: str | Path | UPath

Source GeoTIFF (local or S3).

dst_file: str | Path | UPath

Destination GeoTIFF (local or S3). May be the same as src_file, in which case the file is rewritten in place via the staging file.

profile: dict[str, Any] or None = None

Custom rasterio profile settings. If None, uses deflate compression with 512x512 tiling.

band_names: list[str] or None = None

New band descriptions, one per band. If None, the source’s existing band descriptions are preserved.

color_interp: list[ColorInterp] or None = None

New per-band color interpretation. If None, the source’s existing color interpretation is preserved.

tags: Mapping[str, str] or None = None

Dataset-level tags to merge into the ones carried over from the source.

band_tags: Sequence[Mapping[str, str]] or None = None

Per-band tags, one mapping per band, merged into the ones carried over from the source.

units: list[str] or None = None

New band unit strings, one per band. If None, the source’s existing units are preserved.

move: bool = False

If True, delete src_file after a successful rewrite to a different path (a move). If False (the default), the source is preserved (a copy). Ignored when src_file == dst_file.

Raises

RuntimeError

If the rewrite fails.