GRASS (Geographic Resources Analysis Support System) is an open source GIS with advanced analysis, modeling, and visualization capabilities. GRASS works as a shell environment or a wxWidgets GUI (using wxPython).

The GRASS main program such as grass (link) or grass72 (version specific Python script) can:

  • -c, create location or mapset (and -e exit);
  • --exec, run a GRASS module or a user shell (sh) /Python (python) script;
  • or start a GRASS CLI -text, CLI with graphical greetings -gtext, or GUI (-gui),
  • with mapset specified (<GISDBASE>/<LOCATION_NAME>/ <MAPSET>), or obtained from environment variables (-).
  • Without any options, the main program will start GRASS with the last settings for the user interface and mapset, cached in $HOME/.grass7/rc.

Development of GRASS started in 1987 by USA-CERL, a branch of the U.S. Army Corps of Engineers, with initial release in 1984 for Unix. In comparison, Esri's initial product ARC/INFO was released in 1982 as a command line GIS product on minicomputers, and later on UNIX (v5.0) and Windows (v7.1). CERL stopped supporting GRASS in 1995 (v4.1) and the current project leader is Markus Neteler. The current major version GRASS 7 was released in 2015.


Precedence of GRASS configuration:

  1. Command line argument;
  2. Environment variables in current shell;
  3. GRASS configuration files (under $HOME/.grass7/ for GRASS 7):
    • bashrc, cshrc, zshrc, env.bat, GRASS-related Bash/Csh/Zsh/CMD environment variables;
    • rc, cache of GRASS GIS environment (gisenv) variables, set by g.gisenv set="VARIABLE=VALUE";
  4. Default value;

GRASS does not work very well with zsh, try export SHELL=/bin/bash before calling grass.

GRASS-related shell environment variables: Documentation

  • GISBASE, GRASS library (e.g. /usr/lib/grass72);
  • GISRC, file path for GRASS session gisenv values, $HOME/.grass7/rc for GRASS 7;
  • GRASS_GUI, type of GRASS user interface;
  • GRASS_PYTHON, default python in GRASS GUI overiding shell python;
  • GRASS_HTML_BROWSER, HTML browser for help pages;
  • GRASS_ADDON_BASE, GRASS_ADDON_PATH, extra search paths for repository/local add-on modules;
  • LOCATION, full path of default GRASS mapset;
  • GISDBASE, LOCATION_NAME, MAPSET, default GRASS database/location/mapset;
  • GRASS_MESSAGE_FORMAT, percentage output and message formatting style;
  • GRASS_SH, bourne shell interpreter used to run shell scripts;
  • GRASS_BATCH_JOB, shell script to execute at GRASS launch.

GRASS GIS environment (gisenv) variables:

  • DEBUG, debug message level;
  • GIS_LOCK, lock ID to prevent concurrent GRASS use, default to the process id of the start-up shell script;
  • OVERWRITE, allow map overwrite;
  • GUI;

GRASS Database

Unlike QGIS, GRASS manages geospatial data under a dedicated directory called a GRASS database. Data in external formats such as Shapefile and GeoTIFF are best maintained in a separate location.

GRASS database hierarchy:

  1. GRASS database: the root directory of GRASS data, often /home/$USER/grassdata/.
  2. Location: a projection (GRASS does not do on-the-fly projection transformation).
  3. Mapset: a thematic group of spatial objects and attribute data.

Mapset PERMANENT/ is reserved for default cartography, with files PROJ_INFO, PROJ_UNITS, PROJ_EPSG defining projection and DEFAULT_WIND for default GRASS region.

Mapset structure by data type:

  1. vector
    • vector/, vector maps (each may have coor, dbin, hist command history, sidx, topo);
    • sqlite/, attribute tables managed by SQLite;
    • VAR, database driver and path;
  2. raster: cats/, cell/, cellhd/, cell_misc/, colr/, fcell/, hist/;
    • WIND, GRASS region for raster data;
  3. 3D raster: grid3/, 3D raster maps;

Command history logs are available within each mapset:

Inside the hist directory, you will find command logs for each raster layer. Within the sub-directories vector, you will find the command logs for each vector layer. There is also .bash_history file in the main mapset directory for all commands logs you used during a GRASS session.

Figure: GRASS Directory Structure. Source

GRASS topological vector model:

  • Topological object: for example, areas are defined by boundaries and identified (labelled) by centroid.
  • Layer: a numbered group of spatial objects with one attribute table.
    • Category: a unique ID for each spatial object within a layer.
    • Attribute: a feature associated with a spatial object identified by its category.

GRASS raster model:

  • Raster region: defined by the extent and resolution of a raster map.
  • Computational region: defined by region extent and raster resolution; overrides raster region.
  • Display region: extent of the current map display, independent of computational region and raster region.


GRASS is set up as a modified shell environment where operations are bundled modules: either as standalone executables written in C, or as Python scripts calling them. Near 400 core modules come with the GRASS distribution; user-created add-on modules are available on its website. Most modules read maps from the GRASS database and write new maps back; other types of outputs are either stored in temporary files or put to the standard streams which can be chained with other programs.

Figure: GRASS 7 Architecture. Source

GRASS Reference Manuals have a complete list of modules: List, Grouped, Graphical.

Module groups not documented: m, miscellaneous; ps, PostScript; test, test;

General g

General data management:

g.gisenv, manage GRASS GIS environment variable. g.proj, projection information. g.region, computational region (also display region). g.mapset, manage current mapset. g.list, lists available GRASS database files of a specified type or pattern. g.gui.dbmgr, graphical attribute table manager.

g.extension, manage add-on modules. g.copy, copy data files to the current mapset.

Display d

Graphic output:

d.vect d.vect.thematic, display thematic vector map. d.mon, start/stop/select graphics display monitors; height of display monitor is larger than screen height (37 px for GUI menu). d.erase, cover the active graphics frame with black or a custom color. d.frame, manage display frames on a graphics monitor., rectangle/dimensions of screen/frame, geographic coordinates and resolution of frame.

All color tables are stored in $GISBASE/etc/colors/. Color table type rules: category values (applicable to data with certain ranges) or percent values (applicable to any data), associated with standard GRASS color names or RGB values. The "nv" parameter sets color for NULL values; the "default" parameter sets color undefined values (beyond the range of the color rules).

Example rule file with category values associated with standard GRASS color names:

1 red
2 green
3 blue

Example rule file with percent values associated with RGB values:

0% 255:0:0
50% 0:255:0
100% 0:0:255

Database db

Database integration: SQLite (default DB backend), PostgreSQL, MySQL, ODBC, DBF.

db.connect, database connection., select value(s) from table.

Vector v, imports vector data in OGR supported formats. v.proj, re-projects a vector map from one location to the current location. v.import, imports vector data in OGR supported formats and re-projects on the fly. (add-on module), imports OpenStreetMap data.

v.transform, affine transformation (shift, scale and rotate). v.extract, selects vector objects from an existing vector map and creates a new map., feature select operations (calling GEOS). v.overlay, feature overlay operations. v.db, attribute table management., vector map info (metadata, history, attribute columns). v.colors, manage color table of a vector map.

v.clean, topological cleaning. v.generalize, simplification, smoothing., network analysis (shortest path, subnet allocation, cost isoline, travelling salesman). v.rast.stats, univariate statistics per vector feature based on a raster map. v.lrs, linear referencing (LRS)., populates attribute values from vector features. v.db.update, updates an attribute column.

Raster r & 3D Raster r3, import raster data of common formats (GeoTIFF). r.univar, univariate analysis. r.mapcalc, map calculation., generate surface map. r.grow, grow raster map. r.tile, split a raster map into tiles.

Elevation (DEM) analysis: cost surface: r.cost, r.walk; hydrological modelling: r.watershed, r.terraflow, r.flow, r.drain, r.fill; sight: r.viewshed;

Energy: r.sun, r.sunmask.

Voxel (3D raster) processing: r3.stats, voxel statistics.

Imagery i

i.segment, unsupervised image classification. i.pca, Principal Components Analysis on imagery group.

Temporal t

Temporal processing for spatio-temporal data sets (new in GRASS 7).

data types: t.rast, t.rast3d, t.vect (time series aggregation).


Shell Scripting

OSGeo wiki page on GRASS and Shell

You may include the following in shell scripts to set up a GRASS environment:

export GISBASE=/usr/lib/grass72
export PATH=$GISBASE/bin:$GISBASE/scripts:$PATH
# path to GRASS settings file
export GISRC=$HOME/.grass7/rc
# use process ID (PID) as lock file number
export GIS_LOCK=$$

Cleanup internal temporary files:

rm -rf /tmp/grass6-$USER-$GIS_LOCK

If you change the prompt:

export PS1="GRASS> "
# ... do something with GRASS
export PS1=$PS1_BACKUP


GRASS as an open source GIS backbone:

  • C libraries: GRASS GIS 7 Programmer's Manual
  • Python: PyGRASS, GRASS 7 API (scripting via GRASS modules, interface to C libraries); PyWPS, python web processing service (OGC Web Services).
  • R: Using R within GRASS GIS session (Start R or RStudio in a GRASS shell, then load rgrass7); Using GRASS GIS within a R session (call rgrass7::initGRASS()).
  • QGIS: calls GRASS either via Toolbox (direct connection) or Processing (virtual session).
  • ParaView (visualization)

🏷 Category=Geographic Information System