g.extension(1grass) GRASS GIS User's Manual g.extension(1grass)
NAME
g.extension - Maintains GRASS Addons extensions in local GRASS instal-
lation.
Downloads and installs extensions from GRASS Addons repository or other
source into the local GRASS installation or removes installed exten-
sions.
KEYWORDS
general, installation, extensions, addons, download
SYNOPSIS
g.extension
g.extension --help
g.extension [-lcgasdiftoj] 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 reposi-
tory
-c
List available extensions in the official GRASS GIS Addons reposi-
tory including module description
-g
List available extensions in the official GRASS GIS Addons reposi-
tory (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
-j
Generates JSON file containing the download URLs of the official
Addons
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
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
Options: 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)
DESCRIPTION
g.extension downloads and installs, removes or updates extensions (ad-
dons) from the official GRASS GIS Addons repository or from user-speci-
fied source code repositories into the local GRASS GIS installation.
Two types of extensions are supported:
• Python scripts: they are installed without the need of compila-
tion 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 GIS extension is down-
loaded pre-compiled from the GRASS GIS site, on Unix based sys-
tems 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 GIS Addon extension re-in-
stalls the requested extension which may include updates.
To bulk-update all locally installed GRASS GIS extensions, g.exten-
sion.all module is available.
Where the extensions are installed
GRASS GIS extensions are installed by g.extension into a dedicated di-
rectory. The default is a directory for application data and settings
inside the user’s home directory. On GNU/Linux it is $HOME/.grass7/ad-
dons, on MS-Windows it is $APPDATA\GRASS7\addons. The name of the di-
rectory is stored in the GRASS_ADDON_BASE environmental variable.
The flag -s changes this install target directory to the GRASS GIS in-
stallation directory (determined by GISBASE environmental variable,
e.g. /usr/) rather than the default directory defined as per GRASS_AD-
DON_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 GIS is in this case in the responsibility of the user.
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. 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 develop-
ing a new module. To keep the directory clean, the directory content
is copied to a temporary directory and the compilation happens there.
Local source code ZIP file
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 web (specified by an URL).
Online repositories: GitHub, GitLab and Bitbucket
For well known general hosting services, namely GitHub, GitLab and Bit-
bucket, g.extension supports the download of a repository as a ZIP
file. Here the user only needs to provide a base URL to the repository
web page (with or without the https:// part). For GitLab and Bit-
bucket, the latest source code in the default branch is downloaded, for
GitHub, the latest source code in the master branch is downloaded. Of
course, a user can still specify the full URL of a ZIP file and install
a specific branch or release in this way (ZIP file mechanism will be
applied).
For the official repository, g.extension supports listing available ex-
tensions (addons) and few other metadata-related operations which de-
pend 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.
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 svn 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 read-
ily locally installed, g.extension downloads a precompiled executable
from the GRASS GIS 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 lo-
cally. 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 com-
piled, not only the source code (which is really necessary to compile
just in case of C).
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 conve-
nience, 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 reposi-
tory:
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 of-
ficial 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 Trac code browser and include Subversion revision num-
ber. For example, this installs the version number 57854 of r.local.re-
lief 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 in-
stall it using:
g.extension r.example url=/local/directory/r.example/
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
Since extensions have to be compiled on Unix based systems (Linux, Mac
OSX etc.) unless a Python extension is installed, a full compiler en-
vironment must be present on the user’s computer.
ERROR: Please install GRASS development package
While GRASS GIS is available on the user’s computer, the respective de-
velopment 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 in-
stalled.
SEE ALSO
g.extension.all
GRASS GIS 7 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 OSGeoREL (support for general sources, partial
refactoring)
SOURCE CODE
Available at: g.extension source code (history)
Accessed: unknown
Main index | General index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 g.extension(1grass)
Generated by dwww version 1.14 on Fri Jan 24 06:22:40 CET 2025.