g.extension

Maintains GRASS Addons extensions in local GRASS installation.

Downloads and installs extensions from GRASS Addons repository or other source into the local GRASS installation or removes installed extensions.

Command linePython (grass.tools)Python (grass.script)

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

Example:

g.extension extension=name operation=add

grass.tools.Tools.g_extension(extension, operation="add", url=None, prefix="$GRASS_ADDON_BASE", proxy=None, branch=None, flags=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.g_extension(extension="name", operation="add")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.parse_command("g.extension", extension, operation="add", url=None, prefix="$GRASS_ADDON_BASE", proxy=None, branch=None, flags=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("g.extension", extension="name", operation="add")

Parameters

Command linePython (grass.tools)Python (grass.script)

extension=name [required]
    Name of extension to install or remove
    Name of toolbox (set of extensions) when -t flag is given
operation=string [required]
    Operation to be performed
    Allowed values: add, remove
    Default: add
url=url
    URL or directory to get the extension from (supported only on Linux and Mac)
    The official repository is used by default. User can specify a ZIP file, directory or a repository on common hosting services. If not identified, Subversion repository is assumed. See manual for all options.
prefix=path
    Prefix where to install 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 addon from (only used when fetching from git)
-l
    List available extensions in the official GRASS Addons repository
-c
    List available extensions in the official GRASS Addons repository including module description
-g
    List available extensions in the official GRASS Addons repository (shell script style)
-a
    List locally installed extensions
-s
    Install system-wide (may need system administrator rights)
-d
    Download source code and exit
-i
    Do not install new extension, just compile it
-f
    Force removal when uninstalling extension (operation=remove)
-t
    Operate on toolboxes instead of single modules (experimental)
-o
    url refers to a fork of the official extension repository
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

extension : str, required
    Name of extension to install or remove
    Name of toolbox (set of extensions) when -t flag is given
    Used as: name
operation : str, required
    Operation to be performed
    Allowed values: add, remove
    Default: add
url : str, optional
    URL or directory to get the extension from (supported only on Linux and Mac)
    The official repository is used by default. User can specify a ZIP file, directory or a repository on common hosting services. If not identified, Subversion repository is assumed. See manual for all options.
    Used as: url
prefix : str, optional
    Prefix where to install extension (ignored when flag -s is given)
    Used as: path
    Default: $GRASS_ADDON_BASE
proxy : str | list[str], optional
    Set the proxy with: "http=<value>,ftp=<value>"
    Used as: proxy
branch : str, optional
    Specific branch to fetch addon from (only used when fetching from git)
    Used as: branch
flags : str, optional
    Allowed values: l, c, g, a, s, d, i, f, t, o
    l
        List available extensions in the official GRASS Addons repository
    c
        List available extensions in the official GRASS Addons repository including module description
    g
        List available extensions in the official GRASS Addons repository (shell script style)
    a
        List locally installed extensions
    s
        Install system-wide (may need system administrator rights)
    d
        Download source code and exit
    i
        Do not install new extension, just compile it
    f
        Force removal when uninstalling extension (operation=remove)
    t
        Operate on toolboxes instead of single modules (experimental)
    o
        url refers to a fork of the official extension repository
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

grass.tools.ToolError: When the tool ended with an error.

extension : str, required
    Name of extension to install or remove
    Name of toolbox (set of extensions) when -t flag is given
    Used as: name
operation : str, required
    Operation to be performed
    Allowed values: add, remove
    Default: add
url : str, optional
    URL or directory to get the extension from (supported only on Linux and Mac)
    The official repository is used by default. User can specify a ZIP file, directory or a repository on common hosting services. If not identified, Subversion repository is assumed. See manual for all options.
    Used as: url
prefix : str, optional
    Prefix where to install extension (ignored when flag -s is given)
    Used as: path
    Default: $GRASS_ADDON_BASE
proxy : str | list[str], optional
    Set the proxy with: "http=<value>,ftp=<value>"
    Used as: proxy
branch : str, optional
    Specific branch to fetch addon from (only used when fetching from git)
    Used as: branch
flags : str, optional
    Allowed values: l, c, g, a, s, d, i, f, t, o
    l
        List available extensions in the official GRASS Addons repository
    c
        List available extensions in the official GRASS Addons repository including module description
    g
        List available extensions in the official GRASS Addons repository (shell script style)
    a
        List locally installed extensions
    s
        Install system-wide (may need system administrator rights)
    d
        Download source code and exit
    i
        Do not install new extension, just compile it
    f
        Force removal when uninstalling extension (operation=remove)
    t
        Operate on toolboxes instead of single modules (experimental)
    o
        url refers to a fork of the official extension repository
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

g.extension downloads and installs, removes or updates extensions (addons) from the official GRASS Addons repository or from user-specified source code repositories into the local GRASS installation.

Two types of extensions are supported:

Python scripts: they are installed without the need of compilation or (usually) the need of special dependencies.
Source code (mostly written in C programming language; may also be written in C++, Fortran or other languages): while on MS-Windows systems the requested GRASS extension is downloaded pre-compiled from the GRASS site, on Unix based systems the installation is preceded by the automated download of the extension's source code along with subsequent compilation and installation. This requires a compiler environment to be present on the user's computer.

Managing installed extensions

Re-running g.extension on an installed GRASS Addon extension re-installs the requested extension which may include updates.

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

Where the extensions are installed

GRASS 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, on MS-Windows it is %APPDATA%\Roaming\GRASS8\addons. The name of the directory is stored in the GRASS_ADDON_BASE environmental variable.

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

The place where the extensions are installed can be customized by the option prefix. Ensuring that these extensions will be accessible in GRASS is in this case in the responsibility of the user.

Source code sources and repositories

GRASS Addons repository on GitHub

By default, g.extension installs extensions from the official GRASS Addons GitHub repository. However, 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 latter, however, works only for certain directories where the download of ZIP files was enabled by project administrators of the trac server.

Local source code directory

Optionally, new extension can be also installed from a source code placed in a local directory on disk. This is advantageous when 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, new extension can be also 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 the download of a repository. Here the user only needs 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. Of course, a user can still specify the full URL of a ZIP file e.g. for a specific release and install the archived code in this way (ZIP file mechanism will be applied).

For the official repository, g.extension supports listing available extensions (addons) and few other metadata-related operations which depend on a specific infrastructure. For other sources and repositories, this is not supported because it is 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 that 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 project server. On all other operating systems where it is not difficult to install compilation tools, g.extension downloads the source code of the requested extension (addon) and compiles it locally. This applies for both C and Python modules as well as any other extensions. The reason is that more things such as manual page are compiled, not only the source code (which is really necessary to compile just in case of C).

Using an alternative addon server (MS-Windows)

On MS-Windows, g.extension downloads precompiled addon ZIPs from the official WinGRASS server (http://wingrass.fsv.cvut.cz) by default. The base URL of the server can be redirected to a mirror or a private addon server by setting ADDONS_BASE_URL. The setting affects both the addon listing (g.extension -l, -c, -g) and the install download URL, so listing and install always come from the same place.

The alternative server must host the precompiled addon ZIPs in the directory layout {base}/grass{MM}/addons/grass-{M.M.P}/ (for example .../grass85/addons/grass-8.5.0/), one ZIP per extension, together with a modules.xml file listing them in that same directory (and a toolboxes.xml file if toolbox operations with -t are to be used). Note that this setup differs from the official WinGRASS server, where the addon listing is served separately from grass.osgeo.org, so an exact mirror of the official server would install addons but fail on g.extension -l.

The setting can be applied in two ways:

From inside GRASS (persists across sessions, settable from the GUI's variables panel as well):

g.gisenv set="ADDONS_BASE_URL=https://your.server.example"

As a shell environment variable named GRASS_ADDONS_BASE_URL (useful for one-off shell sessions or CI jobs). The environment variable takes precedence over the gisenv setting; if neither is set, the default WinGRASS server is used.

To revert to the default server, unset the value:

g.gisenv unset=ADDONS_BASE_URL

Alternative servers are:

https://ecodiv.earth/share/AddonServer (Python extensions only)

Note that the settings explained in this section are honoured on MS-Windows only; on Linux/macOS they have no effect.

EXAMPLES

Download and install of an extension

Download and install r.stream.distance into 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

Installing from an alternative addon server (MS-Windows)

On MS-Windows, redirect the addon server to a mirror or private host, then use g.extension normally; listing and install both go through the configured server.

# Point at the alternative server (persists across GRASS sessions)
g.gisenv set="ADDONS_BASE_URL=https://ecodiv.earth/share/AddonServer"

# List what the alternative server provides
g.extension -l

# Install an extension from it
g.extension extension=r.tpi

# Revert to the default WinGRASS server
g.gisenv unset=ADDONS_BASE_URL

For a one-off shell session, set the environment variable instead:

# cmd.exe
set GRASS_ADDONS_BASE_URL=https://ecodiv.earth/share/AddonServer
g.extension extension=r.tpi

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

On MS-Windows, addons are not compiled locally, so url must point directly at a ZIP file of a single precompiled addon (the URL has to end in .zip); a source archive such as the one in the example above will not work. To install from a different addon server instead, redirect the server with ADDONS_BASE_URL (see Using an alternative addon server above).

Install a specific version from Addons

To install a specific version from GRASS Addons, specify the full URL pointing to Trac code browser and include Subversion revision number. For example, this installs the version number 57854 of 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 one 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, modules cannot be compiled locally (a Python replacement for Python scripts should be implemented), so g.extension installs precompiled binaries. These come from the official WinGRASS server by default, but the server can be redirected to an alternative host that provides precompiled addon ZIPs together with a modules.xml listing (and a toolboxes.xml for -t) in the layout {base}/grass{MM}/addons/grass-{M.M.P}/. See Using an alternative addon server for details.

TROUBLESHOOTING

Since extensions have to be compiled on Unix based systems (Linux, Mac OSX etc.) unless a Python extension is installed, a full compiler environment must be present on the user's computer.

ERROR: Please install GRASS development package

While GRASS is available on the user's computer, the respective development package is lacking. If GRASS was installed from a (Linux) repository, also the grass-dev* package (commonly named "grass-dev" or "grass-devel", sometimes along with the version number) must be installed.

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)
Paulo van Breugel, HAS green academy (add option for Windows users to point at alternative repositories)

SOURCE CODE

Available at: g.extension source code (history)
Latest change: Thursday Nov 05 04:57:09 2026 in commit d933a5c

g.extension

Parameters

DESCRIPTION

Managing installed extensions

Where the extensions are installed

Source code sources and repositories

GRASS Addons repository on GitHub

Local source code directory

Source code in a ZIP or TAR archive

Online repositories: GitHub, GitLab and Bitbucket

Needed directory layout

Compilation and installation

Using an alternative addon server (MS-Windows)

EXAMPLES

Download and install of an extension

Installing from an alternative addon server (MS-Windows)

Download and install of an extension when behind a proxy

Managing the extensions

Installing from various online repositories: GitHub, GitLab, Bitbucket

Install a specific version from Addons

Installing when writing a module locally

REQUIREMENTS

KNOWN ISSUES

TROUBLESHOOTING

ERROR: Please install GRASS development package

SEE ALSO

AUTHORS

SOURCE CODE