variables(1)

📦
version 8.4.2 · 10 versions
, in fedora 44

💖 variables(1) — GRASS variables and environment variables 💖

okay bestie, sit down, we're doing the GRASS GIS User's Manual thing and honestly this one is a whole vibe. 🌈

A variable in scripting is a symbolic name that holds data which can be used and modified during script execution. Variables allow scripts to store and manipulate values dynamically, making them more flexible and reusable. fr fr, they're the main character of reusability. In GRASS GIS, there are two types of variables:

  • shell environment variables,
  • GRASS gisenv variables.

And there are a number of shell environment variable groups:

  • variables for rendering
  • variables for internal use
Note: Any setting which needs to be modifiable by a GRASS module (e.g. MONITOR by d.mon) has to be a GRASS gisenv variable. like… it's not optional bestie, it HAS to be gisenv.

🌸 Setting shell environment variables 🌸

Setting shell environment variables depends on the shell being used:

Bash:

export VARIABLE=value

Csh:

setenv VARIABLE value

Cmd.exe (Windows):

set VARIABLE=value

To set up shell environment variables permanently:

  • To get personal BASH shell definitions (aliases, color listing option, ...) into GRASS, store them in: $HOME/.grass8/bashrc
  • To get personal CSH shell definitions (aliases, color listing option, ...) into GRASS, store them in: $HOME/.grass8/cshrc

✨ Setting GRASS gisenv variables ✨

Use g.gisenv within GRASS. This permanently predefines GRASS variables in the $HOME/.grass8/rc file (Linux, Mac, BSD, ...) or in the %APPDATA%\Roaming\GRASS8\rc file (Windows) after the current GRASS session is closed.

Usage:

g.gisenv set="VARIABLE=VALUE"

It looks unusual with two equals signs, but g.gisenv serves dual duty for getting and setting GRASS variables. two jobs, one icon 💅

If the user just specifies a variable name, it defaults to get mode. For example:

g.gisenv MAPSET
PERMANENT

[ To be set from the terminal shell or startup scripts ]

  • GISBASE — directory where GRASS lives. This is set automatically by the startup script. she sets herself, no need to lift a finger.
  • GISRC — name of $HOME/.grass8/rc file. Defines the system wide value when starting a GRASS session. Within a GRASS session, a temporary copy of this file will be used.
  • GRASS_ADDON_PATH [grass startup script, g.extension] — specifies additional path(s) containing local and/or custom GRASS modules extra to the standard distribution.
  • GRASS_ADDON_BASE [grass startup script] — allows specifying additional GISBASE for local GRASS modules (normally installed as GRASS Addons by g.extension module) extra to standard distribution. The default on GNU/Linux is $HOME/.grass8/addons, on MS Windows %APPDATA%\Roaming\GRASS8\addons.
  • GRASS_ADDON_ETC [libgis, g.findetc] — specify paths where support files (etc/) may be found external to standard distribution.
  • GRASS_COMPATIBILITY_TEST [libgis] — By default it is not possible to run C modules with a libgis that has a different GIS_H_VERSION, the compatibility test will exit with a fatal error. Setting this variable to 0 (zero) with GRASS_COMPATIBILITY_TEST=0 allows the test to be passed with a warning. she's strict but she can be negotiated with.
  • GRASS_COMPRESSOR [libraster] — the compression method for new raster maps can be set with the environment variable GRASS_COMPRESSOR. Supported methods are RLE, ZLIB, LZ4, BZIP2, and ZSTD. The default is ZSTD if available, otherwise ZLIB, which can be changed with e.g. GRASS_COMPRESSOR=ZSTD, granted that GRASS has been compiled with the requested compressor. Compressors that are always available are RLE, ZLIB, and LZ4. The compressors BZIP2 and ZSTD must be enabled when configuring GRASS for compilation.
  • GRASS_CONFIG_DIR [grass startup script] — specifies root path for GRASS configuration directory. If not specified, the default placement of the configuration directory is used: $HOME on GNU/Linux, $HOME/Library on Mac OS X, and %APPDATA% on MS Windows.
  • GRASS_DB_ENCODING [various modules, wxGUI] — encoding for vector attribute data (utf-8, ascii, iso8859-1, koi8-r)
  • GIS_ERROR_LOG — If set, GIS_ERROR_LOG should be the absolute path to the log file (a relative path will be interpreted relative to the process' cwd, not the cwd at the point the user set the variable). If not set, $HOME/GIS_ERROR_LOG is used instead. The file will only be used if it already exists.
  • GRASS_ERROR_MAIL — set to any value to send user mail on an error or warning that happens while stderr is being redirected.
  • GRASS_FONT [display drivers] — specifies the font as either the name of a font from $GISBASE/etc/fontcap (or alternative fontcap file specified by GRASS_FONT_CAP), or alternatively the full path to a FreeType font file.
  • GRASS_ENCODING [display drivers] — the encoding to be assumed for text which is drawn using a freetype font; may be any encoding know to iconv.
  • GRASS_FONT_CAP [g.mkfontcap, d.font, display drivers] — specifies an alternative location (to $GISBASE/etc/fontcap) for the font configuration file.
  • GRASS_FULL_OPTION_NAMES [parser] — Generates a warning if GRASS_FULL_OPTION_NAMES is set (to anything) and a found string is not an exact match for the given string. she's a perfectionist, respect it.
  • GRASS_GUI — either text (text user interface), gtext (text user interface with GUI welcome screen), or gui (graphical user interface) to define non-/graphical startup. Can also specify the name of the GUI to use, e.g. wxpython (wxGUI). Also exists as a GRASS gisenv variable (see below). If this shell variable exists at GRASS startup, it will determine the GUI used. If it is not defined startup will default to the last GUI used.
  • GRASS_HTML_BROWSER [init.sh, wxgui] — defines name of HTML browser. For most platforms this should be an executable in your PATH, or the full path to an executable.

Mac OS X runs applications differently from the CLI. Therefore, GRASS_HTML_BROWSER should be the application's signature, which is a domain-like name, just reversed, i.e. com.apple.Safari. To find an application's signature, type the following in a Terminal (fill in the path to the application you are interested in, for example: /Applications/Safari.app):

grep -A 1 "CFBundleIdentifier"
/path/to/application.app/Contents/Info.plist

The signature is the <string> following the <key>, without the bracketing <string> tags.

  • GRASS_INT_ZLIB [libraster] — if the environment variable GRASS_INT_ZLIB exists and has the value 0, new compressed integer (CELL type) raster maps will be compressed using RLE compression.

If the variable doesn't exist, or the value is non-zero, zlib compression will be used instead. Such rasters will have a compressed value of 2 in the cellhd file.

Obviously, decompression is controlled by the raster's compressed value, not the environment variable.

  • GRASS_ZLIB_LEVEL [libgis] — if the environment variable GRASS_ZLIB_LEVEL exists and its value can be parsed as an integer, it determines the compression level used when new compressed raster maps are compressed using zlib compression. This applies to all raster map types (CELL, FCELL, DCELL).

Valid zlib compression levels are -1 to 9. The GRASS_ZLIB_LEVEL=-1 corresponds to the zlib default value (equivalent to GRASS_ZLIB_LEVEL=6). Often GRASS_ZLIB_LEVEL=1 gives the best compromise between speed and compression.

If the variable doesn't exist, or the value cannot be parsed as an integer, zlib's default compression level 6 will be used.

  • GRASS_MESSAGE_FORMAT [various modules, wxGUI] — it may be set to either
    • standard - sets percentage output and message formatting style to standard formatting,
    • gui - sets percentage output and message formatting style to GUI formatting,
    • silent - disables percentage output and error messages,
    • plain - sets percentage output and message formatting style to ASCII output without rewinding control characters.
  • GRASS_MOUSE_BUTTON [various modules] — swaps mouse buttons for two-button or left-handed mice. Its value has three digits 1, 2, and 3, which represent default left, middle, and right buttons respectively. Setting to 132 will swap middle and right buttons. Note that this variable should be set before a display driver is initialized (e.g., d.mon x0). set it early or she won't hear you.
  • GRASS_PAGER [various modules] — it may be set to either less, more, or cat.
  • GRASS_PERL [used during install process for generating man pages] — set Perl with path.
  • GRASS_PROXY [used during addon install/reinstall process for generating man pages (download commit from GitHub API server and remote modules.xml file)] — set the proxy with: GRASS_PROXY="http=<value>,ftp=<value>".
  • GRASS_SKIP_MAPSET_OWNER_CHECK — By default it is not possible to work with MAPSETs that are not owned by current user. Setting this variable to any non-empty value allows the check to be skipped. careful bestie, that's a permission door you're opening.
  • GRASS_SH [shell scripts on Windows] — path to bourne shell interpreter used to run shell scripts.
  • GRASS_SIGSEGV_ON_ERROR [Raise SIGSEGV if an error occurs] — This variable can be set for debugging purpose. The call of G_fatal_error() will end in a segmentation violation. GDB can be used to trace the source of the error. yes it crashes on purpose, that's the whole point, iykyk.
  • GRASS_PYTHON [wxGUI, Python Ctypes] — set to override Python executable.

On Mac OS X this should be the pythonw executable for the wxGUI to work.

  • GRASS_VECTOR_LOWMEM [vectorlib] — If the environment variable GRASS_VECTOR_LOWMEM exists, memory consumption will be reduced when building vector topology support structures. Recommended for creating large vectors.
  • GRASS_VECTOR_OGR [vectorlib, v.external.out] — If the environment variable GRASS_VECTOR_OGR exists and vector output format defined by v.external.out is PostgreSQL, vector data is written by OGR data provider even the native PostGIS data provider is available.

okay that's part 1 of this page and there's more coming, so don't go anywhere bestie 💖

  • GRASS_VECTOR_EXTERNAL_IMMEDIATE [vectorlib, v.external.out] — if this one exists and the vector output format set by v.external.out is non-native, then vector features get written straight out to the external datasource, like, immediately. 💨 Normally the vector library is a lil procrastinator: it writes output into a temporary vector map in native format, and only when you close the map does it move everything over to the external datasource. But — heads up — if the output vector format is the topological PostGIS format, the vector library writes features immediately to the output database anyway, and in that case GRASS_VECTOR_EXTERNAL_IMMEDIATE is just ignored. 💀
  • GRASS_VECTOR_EXTERNAL_IGNORE [vectorlib] — if this exists, the output vector format from v.external.out is ignored entirely and the format is always native. no cap.
  • GRASS_VECTOR_TEMPORARY [vectorlib] — if this exists, the GRASS vector library operates on temporary vector maps. New vector maps get created in the temporary directory (peep the GRASS_VECTOR_TMPDIR_MAPSET variable), and existing vector maps will be read from this directory too, if they're found there. You can set it to either:
    • keep — the temporary vector map is not deleted when closing the map.
    • move — the temporary vector map is moved to the current mapset when closing the map.
    • delete — the temporary vector map is deleted when closing the map.

Default value is keep. And note that temporary vector maps are not visible to the user via g.list or wxGUI — they're used internally by the GRASS modules and deleted automatically when the GRASS session is quited. 🙈

  • GRASS_VECTOR_TMPDIR_MAPSET [vectorlib] — by default the GRASS temporary directory lives in $LOCATION/$MAPSET/.tmp/$HOSTNAME. If GRASS_VECTOR_TMPDIR_MAPSET is set to '0', the temporary directory lives in TMPDIR instead (that's the environmental variable defined by the user, or by the GRASS initialization script if you didn't give one).
Important note: this variable is currently used only in the vector library. In other words, the variable is ignored by the raster or raster3d library. 😭
  • GRASS_VECTOR_TOPO_DEBUG [vectorlib, v.generalize] — if this exists, v.generalize runs in an extremely slow debug mode. 🐌 iconic for debugging, tragic for your patience.
  • GRASS_WXBUNDLED [wxGUI] — set it to tell wxGUI that a bundled wxPython will be used. When it's set, the wxGUI will not check the wxPython version, because that check is incompatible with a bundled wxPython. It's up to the packager to make sure a compatible wxPython version is bundled. 🎀
  • GRASS_WXVERSION [wxGUI] — set it to tell wxGUI which version of wxPython to use. When set, wxGUI selects the given wxPython version. Super useful when you've got multiple versions of wxPython installed and you wanna run wxGUI with a non-default one. ✨
  • GRASS_XTERM [lib/init/grass-xterm-wrapper, lib/init/grass-xterm-mac] — set it to any value (like rxvt, aterm, gnome-terminal, konsole) to substitute 'x-terminal-emulator' or 'xterm'. The Mac OS X app startup defaults to an internal '$GISBASE/etc/grass-xterm-mac', which emulates the necessary xterm functionality in Terminal.app. 🍓
  • GRASS_UI_TERM — set to any value to use the terminal based parser.
  • GRASS_VERSION — reports the current version number (used by the R-stats interface etc). Should not be changed by user. hands off bestie 🙅
  • GRASS_NO_GLX_PBUFFERS [nviz] — set to any value to disable the use of GLX Pbuffers.
  • GRASS_NO_GLX_PIXMAPS [nviz] — set to any value to disable the use of GLX Pixmaps.
  • OMP_NUM_THREADS [OpenMP] — if OpenMP support is enabled, this limits the number of threads. The default is set to the number of CPUs on the system. Setting it to '1' effectively disables parallel processing.
  • TMPDIR, TEMP, TMP [Various GRASS GIS commands and wxGUI] — the default wxGUI temporary directory is chosen from a platform-dependent list, but you can control which directory gets picked by setting one of the TMPDIR, TEMP or TMP environment variables. So the wxGUI uses $TMPDIR if it's set, then $TEMP, otherwise /tmp. 🫶

🌈 List of selected GRASS environment variables for rendering 🌈

[ In addition to those which are understood by specific GRASS display drivers, the following variables affect rendering. ]
  • GRASS_RENDER_IMMEDIATE — tells the display library which driver to use. Possible values: cairo, png, ps, html or default. Default display driver is cairo (if available) otherwise png.
  • GRASS_RENDER_WIDTH — defines the width of the output image (default is 640).
  • GRASS_RENDER_HEIGHT — defines the height of the output image (default is 480).
  • GRASS_RENDER_FILE — the name of the resulting image file.
  • GRASS_RENDER_FRAME — contains 4 coordinates, top,bottom,left,right (pixel values) with respect to the top left corner of the output image, defining the initial frame.
  • GRASS_RENDER_LINE_WIDTH — defines default line width.
  • GRASS_RENDER_TEXT_SIZE — defines default text size.
  • GRASS_RENDER_COMMAND — external command called by the display library to render data (see the example in the display drivers page for details). Currently only Python scripts are supported. For specific driver-related variables see:
    • Cairo display driver
    • PNG display driver
    • PS (Postscript) display driver
    • HTML display driver

🫧 List of selected internal GRASS environment variables 🫧

[ These variables are intended for internal use only by the GRASS software, to facilitate communication between the GIS engine, GRASS scripts, and the GUI. The user should not set these in a GRASS session. They are meant to be set locally for specific commands. ]
  • GRASS_OVERWRITE [all modules] — toggles map overwrite.
    • 0 — maps are protected (default),
    • 1 — maps with identical names will be overwritten.

This variable is automatically created by g.parser so that the --overwrite option will be inherited by dependent modules as the script runs. Setting either the GRASS_OVERWRITE environment variable or the OVERWRITE gisenv variable detailed below will cause maps with identical names to be overwritten. 💥

  • GRASS_VERBOSE [all modules] — toggles verbosity level.
    • -1 — complete silence (also errors and warnings are discarded)
    • 0 — only errors and warnings are printed
    • 1 — progress and important messages are printed (percent complete)
    • 2 — all module messages are printed
    • 3 — additional verbose messages are printed

This variable is automatically created by g.parser so that the --verbose or --quiet flags will be inherited by dependent modules as the script runs.

  • GRASS_REGION [libgis] — override region settings, separate parameters with a ";". Format is the same as in the WIND region settings file. Otherwise use is the same as WIND_OVERRIDE.
  • WIND_OVERRIDE [libgis] — it causes programs to use the specified named region (created with e.g. g.region save=...) as the current region, instead of the region from the WIND file. This lets programs like the GUI run external commands on an alternate region without having to modify the WIND file and then change it back afterwards. 🧚

👑 List of selected GRASS gisenv variables 👑

[ Use g.gisenv to get/set/unset/change them ]
  • DEBUG [entire GRASS] — sets level of debug message output (0: no debug messages)
g.gisenv set=DEBUG=0
  • WX_DEBUG [wxGUI] — sets level of debug message output for wxGUI (0: no debug messages, 1-5 debug levels)
  • GISDBASE — initial database
  • GIS_LOCK — lock ID to prevent parallel GRASS use, process id of the start-up shell script
  • GUI — See GRASS_GUI environmental variable for details.
  • LOCATION — full path to project (previously called location) directory
  • LOCATION_NAME — initial project name
  • MAPSET — initial mapset
  • MEMORYMB [entire GRASS with focus on raster related data processing] — sets the maximum memory to be used (in MB), i.e. the cache size for raster rows
# set to 6 GB (default: 300 MB)
g.gisenv set="MEMORYMB=6000"
  • NPROCS — sets the number of threads for parallel computing
# set to use 12 threads (default: 1)
g.gisenv set="NPROCS=12"
  • OVERWRITE [all modules] — toggles map overwrite.
    • 0 — maps are protected (default),
    • 1 — maps with identical names will be overwritten.

This variable is automatically created by g.parser so that the --overwrite option will be inherited by dependent modules as the script runs. Setting either the GRASS_OVERWRITE environment variable or the OVERWRITE gisenv variable detailed below will cause maps with identical names to be overwritten.

  • $HOME/.grass8/rc — stores the GRASS gisenv variables (not shell environment variables)
  • $HOME/.grass8/bashrc — stores the shell environment variables (Bash only)
  • $HOME/.grass8/env.bat — stores the shell environment variables (MS Windows only)
  • $HOME/.grass8/login — stores the DBMI passwords in this hidden file. Only the file owner can access this file. 🔐
  • $HOME/GIS_ERROR_LOG — if this file exists then all GRASS error and warning messages are logged here. Applies to current user. To generate the file, use:
touch $HOME/GIS_ERROR_LOG

See also GIS_ERROR_LOG variable. Note: On MS Windows the files are stored in %APPDATA%.

🌟 SEE ALSO 🌟

g.gisenv, g.parser

💾 SOURCE CODE 💾

Available at: GRASS variables and environment variables source code (history)

Accessed: Saturday Jan 17 05:40:17 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

and that's a wrap bestie 💖 you just read the whole variables(1) page from the GRASS GIS 8.4.2 Reference Manual — go forth and set your env vars responsibly, and remember: the user should not be setting the internal ones, iykyk. ✨🦋👑

📦 where this page comes from