r.external - GRASS manual
Author: GRASS Development Team
Description: r.external: Links GDAL supported raster data as a pseudo GRASS raster map.
Keywords: raster, import, external

## NAME

r.external - Links GDAL supported raster data as a pseudo GRASS raster map.

## KEYWORDS

raster, import, external

## SYNOPSIS

r.external
r.external --help
r.external [-fojeahvtmr] [input=name] [source=name] output=name [band=integer] [title=phrase] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

### Flags:

-f
  List supported formats and exit
-o
  Override projection check (use current project's CRS)
  Assume that the dataset has the same coordinate reference system as the current project
-j
  Perform projection check only and exit
-e
  Extend region extents based on new dataset
  Also updates the default region if in the PERMANENT mapset
-a
  Auto-adjustment for lat/lon
  Attempt to fix small precision errors in resolution and extents
-h
  Flip horizontally
-v
  Flip vertically
-t
  List available bands including band type in dataset and exit
  Format: band number,type,projection check
-m
  Read data range from metadata
  WARNING: metadata are sometimes approximations with wrong data range
-r
  Create fast link without data range
  WARNING: some modules do not work correctly without known data range
--overwrite
  Allow output files to overwrite existing files
--help
  Print usage summary
--verbose
  Verbose module output
--quiet
  Quiet module output
--ui
  Force launching GUI dialog

### Parameters:

input=name
  Name of raster file to be linked
source=name
  Name of non-file GDAL data source
output=name [required]
  Name for output raster map
band=integer
  Band to select (default is all bands)
title=phrase
  Title for resultant raster map

## DESCRIPTION

r.external allows a user to link a GDAL supported raster file to a binary raster map layer, from any GDAL supported raster map format, with an optional title. The file is not imported but just registered as GRASS raster map.

## NOTES

In essence, r.external creates a read-only link to the original dataset which is only valid if the original dataset remains at the originally indicated directory and filename.

## NULL data handling

GDAL-linked (r.external) maps do not have or use a NULL bitmap, hence r.null cannot manipulate them directly. Here NULL cells are those whose value matches the value reported by the GDALGetRasterNoDataValue() function.

To introduce additional NULL values to a computation based on a GDAL-linked raster, the user needs to either create a mask with with r.mask and then "apply" it using e.g. r.resample or r.mapcalc, or use r.mapcalc to create a copy with the appropriate categories changed to NULL (`if()` condition).

## EXAMPLES

### RGB Orthophoto from GeoTIFF

    # import of all channels (each channel will become a GRASS raster map):
    r.external input=/home/user/data/maps/059100.tif output=ortho
    g.region raster=ortho.3 -p
    d.rgb r=ortho.1 g=ortho.2 b=ortho.3
    r.composite r=ortho.1 g=ortho.2 b=ortho.3 output=ortho.rgb

### Processing workflow without data import and export

External raster maps to be processed can be directly linked using r.external; likewise, results can be written out to standard raster formats with r.external.out (GDAL supported formats):

    # register GeoTIFF file to be used in current mapset:
    r.external input=terra_lst1km20030314.LST_Day.tif output=modis_celsius

    # define output directory for files resulting from GRASS calculation:
    r.external.out directory=$HOME/gisoutput/ format="GTiff"

    # perform GRASS calculation (here: extract pixels > 20 deg C)
    # this stores the output map directly as GeoTIFF:
    r.mapcalc "warm.tif = if(modis_celsius > 20.0, modis_celsius, null() )"

    # cease GDAL output connection and turn back to write GRASS raster files:
    r.external.out -r

    # now use the resulting file elsewhere
    gdalinfo $HOME/gisoutput/warm.tif

## REFERENCES

GDAL Pages: https://gdal.org/

## SEE ALSO

r.import, r.in.gdal, r.external.out

v.import, v.in.ogr, v.external, v.external.out

## AUTHOR

Glynn Clements

## SOURCE CODE

Available at: r.external source code (history)

Latest change: Monday Dec 08 21:47:55 2025 in commit: d3c6479bef77a58e3b5d85259303dbfb9c1babe8

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual