r.external(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

r.external 💅✨

okay bestie, gather round, because this one is a whole vibe. it's r.external(1), straight out of the GRASS GIS User's Manual, and it's here to let you link your fave GDAL raster data into GRASS as a pseudo GRASS raster map. no cap. 🦋

✨ NAME ✨

r.external — links GDAL supported raster data as a pseudo GRASS raster map. that's the whole job. iconic behaviour, honestly. 👑

🌸 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 💖

okay so here's the flag lineup, and every single one of them matters, so don't skip:

  • -f — list all the supported formats and then dip. that's it, that's the flag. ✨
  • -o — override the projection check, and just use the current project's CRS. it literally assumes the dataset has the same coordinate reference system as the current project. use it when you know, yk? 🙈
  • -j — do the projection check and nothing else, then exit. just checking, bestie. 💅
  • -e — extend the region extents based on the new dataset. bonus: it also updates the default region if you're in the PERMANENT mapset. slay.
  • -a — auto-adjustment for lat/lon. it attempts to fix small precision errors in resolution and extents. tiny cleanup, huge difference. 🧚
  • -h — flip horizontally. yes, like a mirror. 🪞
  • -v — flip vertically. upside down era. 🙃
  • -t — list available bands including band type in the dataset, then exit. the format is literally: band number, type, projection check. 📋
  • -m — read data range from metadata. ⚠️ WARNING: metadata are sometimes approximations with wrong data range, so lowkey don't fully trust it.
  • -r — create a fast link without data range. ⚠️ WARNING: some modules do not work correctly without a known data range. so like, fast but risky, iykyk.
  • --overwrite — allow output files to overwrite existing files. chaotic but sometimes necessary 💀
  • --help — print usage summary
  • --verbose — verbose module output
  • --quiet — quiet module output
  • --ui — force launching the GUI dialog. for when you want the pretty buttons 🎀

🌈 PARAMETERS 🌈

  • input=name — name of the raster file to be linked
  • source=name — name of a non-file GDAL data source (yes, those exist)
  • output=name — name for the output raster map. [required] — like, actually required, don't forget it bestie 🫶
  • band=integer — band to select. default is all bands. all of them. the full set. 💜
  • title=phrase — a title for the resultant raster map. give it a little name, it deserves one 🌸

💫 DESCRIPTION 💫

r.external lets a user link a GDAL supported raster file to a binary raster map layer — from any GDAL supported raster map format — with an optional title. and here's the key thing: the file is not imported, it's just registered as a GRASS raster map. it's giving "we're not moving in together, we're just linking" energy. 💅

🔥 NOTES 🔥

in essence, r.external creates a read-only link to the original dataset, and that link is only valid if the original dataset stays at the originally indicated directory and filename. so if you move or rename that file, bestie… the link is gone. periodt. 😭

🌊 NULL data handling

GDAL-linked (r.external) maps do not have or use a NULL bitmap, so r.null cannot manipulate them directly. that's just how it is.

so then, what even are NULL cells here? they're the cells whose value matches the value reported by the GDALGetRasterNoDataValue() function.

to apply NULL handling to a GDAL-linked map, the user needs to either create a MASK (e.g. with r.mask) and then "apply" it using e.g. r.resample, or use r.mapcalc to create a copy with the appropriate categories changed to NULL (via an if() condition). pick your fighter. 🥊

✨ 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

look at those channels become GRASS raster maps. obsessed. 😍

🔄 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

no import, no export, just vibes and GeoTIFFs. this is the workflow that ate. 🔥

📚 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)

Accessed: Saturday Jan 17 05:40:46 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

and that's the whole page bestie 💖 this was r.external(1) from GRASS 8.4.2, accessed Saturday Jan 17 05:40:46 2026, © 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual. go link something cute. slay, hydrate, and remember: read-only links only work if you don't move the file. mwah. 💅✨🎀
📦 where this page comes from