g.extension(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 NAME 💖

okay so first of all, hi, welcome to the g.extension(1) page from the GRASS GIS User's Manual, bestie — this one is a whole ✨main character✨ and it's here to help you keep your GRASS Addons extensions cozy inside your local GRASS installation. 💅

It downloads and installs extensions from the GRASS Addons repository (or literally any other source you point it at) into your local GRASS installation — and it also removes installed extensions when you're done with them. 🫶

🔑 KEYWORDS 🔑

general, installation, extensions, addons, download — that's the vibe check, periodt.

🎀 SYNOPSIS 🎀

g.extension
g.extension --help
g.extension [-lcgasdifto] extension=name operation=string  [url=url]
[prefix=path]   [proxy=proxy[,proxy,...]]   [branch=branch]   [--help]
[--verbose]  [--quiet]  [--ui]

🌈 Flags

  • -l — list available extensions in the official GRASS GIS Addons repository 📋
  • -c — same thing but with the module description included, so you actually know what you're getting 👀
  • -g — list available extensions in the official GRASS GIS Addons repository, but in shell script style 🐚
  • -a — list what's locally installed already 💾
  • -s — install system-wide (heads up: this may need system administrator rights 👑)
  • -d — download the source code and dip, no install 🏃‍♀️
  • -i — do not install the new extension, just compile it 🔨
  • -f — force removal when uninstalling (operation=remove) 💥
  • -t — operate on toolboxes instead of single modules (this one is experimental, so, yk, be chill about it)
  • -o — the url refers to a fork of the official extension repository 🍴
  • --help — print usage summary
  • --verbose — verbose module output 🗣️
  • --quiet — quiet module output 🤫
  • --ui — force launching the GUI dialog 🖥️

🌸 Parameters

  • extension=name [required] — name of the extension to install or remove. When the -t flag is given, this is the name of the toolbox (a set of extensions) instead 🧰
  • operation=string [required] — the operation to be performed. Options: add, remove. Default: add ✅
  • url=url — URL or directory to get the extension from (only supported on Linux and Mac, sorry Windows besties 😭). The official repository is used by default. You can specify a ZIP file, a directory, or a repository on common hosting services. If it can't be identified, a Subversion repository is assumed. See the manual for all the options 📚
  • prefix=path — prefix where to install the extension (ignored when flag -s is given). Default: $GRASS_ADDON_BASE 📁
  • proxy=proxy[,proxy,...] — set the proxy with: "http=<value>,ftp=<value>" 🌐
  • branch=branch — specific branch to fetch the addon from (only used when fetching from git) 🌿

🦋 DESCRIPTION 🦋

g.extension downloads and installs, removes, or updates extensions (addons) from the official GRASS GIS Addons repository, or from source code repositories you specify yourself, straight into your local GRASS GIS installation. ✨

Two types of extensions are supported, and yes they're both iconic:

  • Python scripts — these get installed without needing compilation, and (usually) without needing any special dependencies. easy peasy 🐍
  • Source code (mostly written in C, but it may also be written in C++, Fortran, or other languages) — here's the split: on MS-Windows systems, the requested GRASS GIS extension is downloaded pre-compiled from the GRASS GIS site. But on Unix-based systems, the installation is preceded by an automated download of the extension's source code, followed by compilation and installation. That means you need a compiler environment present on your computer. 🔧

🧹 Managing installed extensions

Re-running g.extension on an already-installed GRASS GIS Addon extension re-installs the requested extension, which may include updates. So yeah, re-running it is basically the update button. 🔁

To bulk-update all your locally installed GRASS GIS extensions, the g.extension.all module is available. 🧺

📂 Where the extensions are installed

GRASS GIS extensions are installed by g.extension into a dedicated directory. The default is a directory for application data and settings inside the user's home directory. On GNU/Linux it is $HOME/.grass8/addons, and on MS-Windows it is %APPDATA%\Roaming\GRASS8\addons. The name of that directory is stored in the GRASS_ADDON_BASE environmental variable. 🏠

The flag -s changes this install target directory to the GRASS GIS installation directory — which is determined by the GISBASE environmental variable, e.g. /usr/ — rather than the default directory defined as per GRASS_ADDON_BASE (see also the documentation for variables). g.extension checks whether the user has permission to write to GISBASE or GRASS_ADDON_BASE. 🔐

The place where the extensions get installed can be customized with the prefix option. But heads up: making sure those extensions are actually accessible in GRASS GIS is, in this case, the user's responsibility. 💅

🌐 Source code sources and repositories

🐙 GRASS GIS Addons repository on GitHub

By default, g.extension installs extensions from the official GRASS GIS Addons GitHub repository. But different sources can be specified using the url option. 🔀

Individual extensions can also be installed by providing a URL to the source code on GitHub or OSGeo Trac. The Trac one, however, only works for certain directories where the download of ZIP files was enabled by the project administrators of the trac server. 🗂️

💻 Local source code directory

Optionally, a new extension can also be installed from source code placed in a local directory on disk. This is advantageous when you're developing a new module. To keep the directory clean, the directory content is copied to a temporary directory, and the compilation happens there. 🧼

🗜️ Source code in a ZIP or TAR archive

In addition, a new extension can be installed from a ZIP file or an archive file from the TAR family (e.g., .tar.gz or .bz2). The file can be on disk (specified with a path), or on the web (specified by an URL). 🌍

🏗️ Online repositories: GitHub, GitLab and Bitbucket

For well-known general hosting services — namely GitHub, GitLab and Bitbucket — g.extension supports downloading a repository. Here you only need to provide a base URL to the repository web page (with or without the https:// part). For GitHub, GitLab and Bitbucket, the latest source code in the default branch is downloaded, unless a specific branch is requested in the branch option. And of course, you can still specify the full URL of a ZIP file, e.g. for a specific release, and install the archived code that way (the ZIP file mechanism will be applied). 🎯

For the official repository, g.extension supports listing available extensions (addons) and a few other metadata-related operations which depend on a specific infrastructure. For other sources and repositories, this is not supported, because it's assumed that other sources contain only one extension — typically a module or group of modules with a Makefile at the root of the repository. 📌

🧭 Needed directory layout

When none of the above sources is identified, g.extension assumes the source is in a GitHub repository and uses the git command line tool to obtain the source code. The expected structure of the repository should be the same as the one of the official repository. 🏛️

Non-official sources are supported on all operating systems except for MS-Windows. 🙈

🔨 Compilation and installation

On MS-Windows systems, where compilation tools are typically not readily locally installed, g.extension downloads a precompiled executable from the GRASS GIS project server. On all other operating systems, where it's not difficult to install compilation tools, g.extension downloads the source code of the requested extension (addon) and compiles it locally. This applies to both C and Python modules as well as any other extensions. The reason? More things, such as the manual page, get compiled — not only the source code (which is really only necessary to compile in the case of C). 🧠

🌸 EXAMPLES 🌸

⬇️ Download and install of an extension

Download and install r.stream.distance into the current GRASS installation:

g.extension extension=r.stream.distance

This installs the extension from the official repository. For convenience, a shorter syntax can be used:

g.extension r.stream.distance

🕵️ Download and install of an extension when behind a proxy

Example for an open http proxy:

# syntax: http://proxyurl:proxyport
g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080"

Example for a proxy with proxy authentication:

# syntax: http://username:password@proxyurl:proxyport
g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080"

🧺 Managing the extensions

List all available extensions in the official GRASS GIS Addons repository:

g.extension -l

List all locally installed extensions:

g.extension -a

Removal of a locally installed extension:

g.extension extension=r.stream.distance operation=remove

🌈 Installing from various online repositories: GitHub, GitLab, Bitbucket

Simple URL to GitHub, GitLab, Bitbucket repositories:

g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus"

Simple URL to GitHub, GitLab, Bitbucket repositories from a specific (e.g. development) branch:

g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus" branch=master

Simple URL to OSGeo Trac (downloads a ZIP file, requires download to be enabled in Trac):

g.extension r.example url=trac.osgeo.org/.../r.example

In general, when a ZIP file or other archive is provided, the full URL can be used:

g.extension r.example url=http://example.com/.../r.example?format=zip
Note that because of MS-Windows operating system architecture, only the official repository is supported on this platform. 🪟

🏷️ Install a specific version from Addons

To install a specific version from GRASS GIS Addons, specify the full URL pointing to the Trac code browser and include the Subversion revision number. For example, this installs the version number 57854 of the r.local.relief module:

g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip"

🛠️ Installing when writing a module locally

Having source code of a GRASS module in a directory on disk, you can install it using:

g.extension r.example url=/local/directory/r.example/

⭐ REQUIREMENTS ⭐

In order to clone source code repositories, the git command line tool is required. The installation of single AddOns is most efficient with versions of git that support so-called sparse checkout, which was introduced with version 2.25. With older versions of git, the entire AddOns repository will be downloaded. 😬

On UNIX-like systems, installation is done with the make command line tool. For AddOns written in C / C++, a respective build environment is needed. 🧱

💀 KNOWN ISSUES 💀

Toolboxes in the official repository cannot be downloaded. 🚫

On MS-Windows, only the official repository is working, because there is no way of compiling the modules (a Python replacement for Python scripts should be implemented). 🪟💔

🛠️ TROUBLESHOOTING 💀

okay bestie, real talk time. here's the thing about extensions: they gotta be compiled on Unix based systems (Linux, Mac OSX etc.) — unless you're installing a Python extension. so unless it's a Python one, a full compiler environment has to be present on the user's computer. like, the whole thing. no shortcuts, no vibes-only installs. ✨

😭 ERROR: Please install GRASS development package

this one is so common and it's giving "why is this happening to me" energy. what's going on: GRASS GIS is available on your computer (yay, slay), but the respective development package is lacking (boo, tragic).

so if you installed GRASS from a (Linux) repository, you also need the grass-dev* package — commonly named grass-dev or grass-devel, sometimes along with the version number. install that and you're back in business. 💅

not me forgetting the dev package literally every single time 🙈 it's a rite of passage fr fr

👀 SEE ALSO

  • g.extension.all
  • GRASS GIS 8 Addons Manual pages
  • GRASS Addons wiki page

👑 AUTHORS

  • Markus Neteler (original shell script)
  • Martin Landa, Czech Technical University in Prague, Czech Republic (Python rewrite)
  • Vaclav Petras, NCSU GeoForAll Lab (support for general sources, partial refactoring)

look at that lineup. icons only. the original shell script, the Python rewrite, and the general-sources glow-up. we love to see it 🫶

📜 SOURCE CODE

Available at: g.extension source code (history)

Accessed: Saturday Jan 17 05:41:52 2026

Main index | General index | Topics index | Keywords index | Graphical index | Full index

and that's a wrap on g.extension(1), bestie 🎀 this whole thing lives in the GRASS GIS 8.4.2 manual, © 2003-2025 GRASS Development Team, and yeah the page footer says GRASS 8.4.2 on the left and g.extension(1) on the right, sourced and dated as above. go install something iconic. periodt. 💖✨🦋

📦 where this page comes from