r.external(1grass)

💖 r.external 💖

okay bestie, welcome to the manual page for r.external — it lives in the GRASS User's Manual and it's literally the glow-up queen of raster linking 👑

It links GDAL supported raster data as a pseudo GRASS raster map. yes. that's the whole vibe. 🦋

✨ 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 every supported format and then dip out. bye 👋
• -o — override the projection check (so it uses the current project's CRS). basically: assume the dataset has the same coordinate reference system as your current project. trust fall 🤝
• -j — do the projection check and only the projection check, then exit. no commitment, just vibes.
• -e — extend the region extents based on the new dataset. also updates the default region if you're in the PERMANENT mapset. growth mindset ✨
• -a — auto-adjustment for lat/lon. it'll attempt to fix those tiny precision errors in resolution and extents. so thoughtful.
• -h — flip horizontally 🪞
• -v — flip vertically 🙃
• -t — list the available bands including band type in the dataset, then exit. the format is: band number, type, projection check 📋
• -m — read the data range from metadata. > WARNING: metadata are sometimes approximations with wrong data range 😭 don't trust everything you read fr fr
• -r — create a fast link without data range. > WARNING: some modules do not work correctly without a known data range 💀 speed isn't everything bestie
• --overwrite — allow output files to overwrite existing files (chaos mode, but consensual)
• --help — print the usage summary 🆘
• --verbose — verbose module output, she's chatty
• --quiet — quiet module output, she's mysterious
• --ui — force launching the GUI dialog 🖱️

🌈 Parameters 🌈

• input=name — name of the raster file to be linked
• source=name — name of a non-file GDAL data source (not a file? not a problem)
• output=name [required] — name for the output raster map. yes you HAVE to name it, this one's mandatory
• band=integer — band to select (default is all bands — she takes the whole set 💅)
• title=phrase — title for the resultant raster map

---

💜 DESCRIPTION 💜

r.external lets you 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 thing, and it's giving very important: the file is not imported, it's just registered as a GRASS raster map. we're linking, not copying. periodt. 💫

---

👑 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 like… don't move it. don't rename it. keep it where it is, bestie, or the whole thing falls apart 😭

🫶 NULL data handling 🫶

GDAL-linked (r.external) maps do not have or use a NULL bitmap, which means r.null cannot manipulate them directly. no cap.

Here, NULL cells are those whose value matches the value reported by the GDALGetRasterNoDataValue() function.

So if you wanna introduce additional NULL values into a computation based on a GDAL-linked raster, you've got two routes, and the user needs to pick one:

1. create a mask with r.mask and then "apply" it using e.g. r.resample or r.mapcalc
2. use r.mapcalc to create a copy with the appropriate categories changed to NULL (the if() condition)

either way you're cooking 🍓

---

🔥 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

---

and that's the whole page bestie 🎀 this was r.external(1grass) from the GRASS User's Manual, brought to you by the © 2003-2026 GRASS Development Team and the GRASS 8.5.0 Reference Manual. last touched Monday Dec 08 21:47:55 2025 in commit d3c6479bef77a58e3b5d85259303dbfb9c1babe8, running on GRASS 8.5.0 — go link something iconic, ily, mwah 💖✨🧚