1variables(1) GRASS GIS User's Manual variables(1)
2
6 There are two types of variables:
7 • shell environment variables,
9 • GRASS gisenv variables.
11 There are a number of shell environment variable groups:
12 • variables for rendering
14 • variables for internal use
16 Note: Any setting which needs to be modifiable by a GRASS module (e.g.
17 MONITOR by d.mon) has to be a GRASS gisenv variable.
18
20 Setting shell environment variables depends on the shell being used:
21 Bash:
22 export VARIABLE=value
23 Csh:
24 setenv VARIABLE value
25 Cmd.exe (Windows):
26 set VARIABLE=value
27 To set up shell environment variables permanently:
28 • To get personal BASH shell definitions (aliases, color listing
30 option, ...) into GRASS, store them in:
31 $HOME/.grass8/bashrc
32 • To get personal CSH shell definitions (aliases, color listing
34 option, ...) into GRASS, store them in:
35 $HOME/.grass8/cshrc
36
38 Use g.gisenv within GRASS. This permanently predefines GRASS variables
39 in the $HOME/.grass8/rc file (Linux, Mac, BSD, ...) or in the %APP‐
40 DATA%\Roaming\GRASS8\rc file (Windows) after the current GRASS session
41 is closed.
42 Usage:
43 g.gisenv set="VARIABLE=VALUE"
44 It looks unusual with two equals signs, but g.gisenv serves dual duty
45 for getting and setting GRASS variables.
46 If the user just specifies a variable name, it defaults to get mode.
48 For example:
49 g.gisenv MAPSET
50 PERMANENT
51
53 [ To be set from the terminal shell or startup scripts ]
54 GISBASE
56 directory where GRASS lives. This is set automatically by the
57 startup script.
58 GISRC
60 name of $HOME/.grass8/rc file. Defines the system wide value when
61 starting a GRASS session. Within a GRASS session, a temporary copy
62 of this file will be used.
63 GRASS_ADDON_PATH
65 [grass startup script, g.extension]
66 specifies additional path(s) containing local and/or custom GRASS
67 modules extra to the standard distribution.
68 GRASS_ADDON_BASE
70 [grass startup script]
71 allows specifying additional GISBASE for local GRASS modules (nor‐
72 mally installed as GRASS Addons by g.extension module) extra to
73 standard distribution. The default on GNU/Linux is
74 $HOME/.grass8/addons, on MS Windows %APPDATA%\Roaming\GRASS8\ad‐
75 dons.
76 GRASS_ADDON_ETC
78 [libgis, g.findetc]
79 specify paths where support files (etc/) may be found external to
80 standard distribution.
81 GRASS_COMPRESSOR
83 [libraster]
84 the compression method for new raster maps can be set with the en‐
85 vironment variable GRASS_COMPRESSOR. Supported methods are RLE,
86 ZLIB, LZ4, BZIP2, and ZSTD. The default is ZSTD if available, oth‐
87 erwise ZLIB, which can be changed with e.g. GRASS_COMPRESSOR=ZSTD,
88 granted that GRASS has been compiled with the requested compressor.
89 Compressors that are always available are RLE, ZLIB, and LZ4. The
90 compressors BZIP2 and ZSTD must be enabled when configuring GRASS
91 for compilation.
92 GRASS_DB_ENCODING
94 [various modules, wxGUI]
95 encoding for vector attribute data (utf-8, ascii, iso8859-1,
96 koi8-r)
97 GIS_ERROR_LOG
99 If set, GIS_ERROR_LOG should be the absolute path to the log file
100 (a relative path will be interpreted relative to the process’ cwd,
101 not the cwd at the point the user set the variable). If not set,
102 $HOME/GIS_ERROR_LOG is used instead. The file will only be used if
103 it already exists.
104 GRASS_ERROR_MAIL
106 set to any value to send user mail on an error or warning that hap‐
107 pens while stderr is being redirected.
108 GRASS_FONT
110 [display drivers]
111 specifies the font as either the name of a font from $GIS‐
112 BASE/etc/fontcap (or alternative fontcap file specified by
113 GRASS_FONT_CAP), or alternatively the full path to a FreeType font
114 file.
115 GRASS_ENCODING
117 [display drivers]
118 the encoding to be assumed for text which is drawn using a freetype
119 font; may be any encoding know to iconv.
120 GRASS_FONT_CAP
122 [g.mkfontcap, d.font, display drivers]
123 specifies an alternative location (to $GISBASE/etc/fontcap) for the
124 font configuration file.
125 GRASS_FULL_OPTION_NAMES
127 [parser]
128 Generates a warning if GRASS_FULL_OPTION_NAMES is set (to anything)
129 and a found string is not an exact match for the given string.
130 GRASS_GUI
132 either text (text user interface), gtext (text user interface with
133 GUI welcome screen), or gui (graphical user interface) to define
134 non-/graphical startup. Can also specify the name of the GUI to
135 use, e.g. wxpython (wxGUI). Also exists as a GRASS gisenv variable
136 (see below). If this shell variable exists at GRASS startup, it
137 will determine the GUI used. If it is not defined startup will de‐
138 fault to the last GUI used.
139 GRASS_HTML_BROWSER
141 [init.sh, wxgui]
142 defines name of HTML browser. For most platforms this should be an
143 executable in your PATH, or the full path to an executable.
144 Mac OS X runs applications differently from the CLI. Therefore,
145 GRASS_HTML_BROWSER should be the application’s signature, which is
146 a domain-like name, just reversed, i.e. com.apple.Safari. To find
147 an application’s signature, type the following in a Terminal (fill
148 in the path to the application you are interested in, for example:
149 /Applications/Safari.app):
150 Â Â grep -A 1 "CFBundleIdentifier" /path/to/application.app/Con‐
151 tents/Info.plist
152 Â The signature is the <string> following the <key>, without the
153 bracketing <string> tags.
154 GRASS_INT_ZLIB
156 [libraster]
157 if the environment variable GRASS_INT_ZLIB exists and has the value
158 0, new compressed integer (CELL type) raster maps will be com‐
159 pressed using RLE compression.
160 If the variable doesn’t exist, or the value is non-zero, zlib com‐
161 pression will be used instead. Such rasters will have a compressed
162 value of 2 in the cellhd file.
163 Obviously, decompression is controlled by the raster’s compressed
164 value, not the environment variable.
165 GRASS_ZLIB_LEVEL
167 [libgis]
168 if the environment variable GRASS_ZLIB_LEVEL exists and its value
169 can be parsed as an integer, it determines the compression level
170 used when new compressed raster maps are compressed using zlib com‐
171 pression. This applies to all raster map types (CELL, FCELL,
172 DCELL).
173 Valid zlib compression levels are -1 to 9. The GRASS_ZLIB_LEVEL=-1
174 corresponds to the zlib default value (equivalent to
175 GRASS_ZLIB_LEVEL=6). Often GRASS_ZLIB_LEVEL=1 gives the best com‐
176 promise between speed and compression.
177 If the variable doesn’t exist, or the value cannot be parsed as an
178 integer, zlib’s default compression level 6 will be used.
179 GRASS_MESSAGE_FORMAT
181 [various modules, wxGUI]
182 it may be set to either
183 • standard - sets percentage output and message formatting style
185 to standard formatting,
186 • gui - sets percentage output and message formatting style to
188 GUI formatting,
189 • silent - disables percentage output and error messages,
191 • plain - sets percentage output and message formatting style to
193 ASCII output without rewinding control characters.
194 GRASS_MOUSE_BUTTON
196 [various modules]
197 swaps mouse buttons for two-button or left-handed mice. Its value
198 has three digits 1, 2, and 3, which represent default left, middle,
199 and right buttons respectively. Setting to 132 will swap middle and
200 right buttons. Note that this variable should be set before a dis‐
201 play driver is initialized (e.g., d.mon x0).
202 GRASS_PAGER
204 [various modules]
205 it may be set to either less, more, or cat.
206 GRASS_PERL
208 [used during install process for generating man pages]
209 set Perl with path.
210 GRASS_PROXY
212 [used during addon install/reinstall process for generating man
213 pages (download commit from GitHub API server and remote mod‐
214 ules.xml file)]
215 set the proxy with: GRASS_PROXY="http=<value>,ftp=<value>".
216 GRASS_SKIP_MAPSET_OWNER_CHECK
218 By default it is not possible to work with MAPSETs that are not
219 owned by current user. Setting this variable to any non-empty value
220 allows the check to be skipped.
221 GRASS_SH
223 [shell scripts on Windows]
224 path to bourne shell interpreter used to run shell scripts.
225 GRASS_SIGSEGV_ON_ERROR
227 Raise SIGSEGV if an error occurs]
228 This variable can be set for debugging purpose. The call of G_fa‐
229 tal_error() will end in a segmentation violation. GDB can be used
230 to trace the source of the error.
231 GRASS_PYTHON
233 [wxGUI, Python Ctypes]
234 set to override Python executable.
235 On Mac OS X this should be the pythonw executable for the wxGUI to
236 work.
237 GRASS_VECTOR_LOWMEM
239 [vectorlib]
240 If the environment variable GRASS_VECTOR_LOWMEM exists, memory con‐
241 sumption will be reduced when building vector topology support
242 structures. Recommended for creating large vectors.
243 GRASS_VECTOR_OGR
245 [vectorlib, v.external.out]
246 If the environment variable GRASS_VECTOR_OGR exists and vector out‐
247 put format defined by v.external.out is PostgreSQL, vector data is
248 written by OGR data provider even the native PostGIS data provider
249 is available.
250 GRASS_VECTOR_EXTERNAL_IMMEDIATE
252 [vectorlib, v.external.out]
253 If the environment variable GRASS_VECTOR_EXTERNAL_IMMEDIATE exists
254 and vector output format defined by v.external.out is non-native,
255 vector features are written to output external datasource immedi‐
256 ately. By default, the vector library writes output data to a tem‐
257 porary vector map in native format and when closing the map, the
258 features are transferred to output external datasource. Note: if
259 output vector format is topological PostGIS format, then the vector
260 library writes features immediately to output database (in this
261 case GRASS_VECTOR_EXTERNAL_IMMEDIATE is ignored).
262 GRASS_VECTOR_EXTERNAL_IGNORE
264 [vectorlib]
265 If the environment variable GRASS_VECTOR_EXTERNAL_IGNORE exists,
266 output vector format defined by v.external.out is ignored. The for‐
267 mat is always native.
268 GRASS_VECTOR_TEMPORARY
270 [vectorlib]
271 If the environment variable GRASS_VECTOR_TEMPORARY exists, GRASS
272 vector library will operate on temporary vector maps. New vector
273 maps will be created in temporary directory (see GRASS_VECTOR_TM‐
274 PDIR_MAPSET variable), existing vector maps will be read (if found)
275 also from this directory. It may be set to either:
276 • keep - the temporary vector map is not deleted when closing the
278 map.
279 • move - the temporary vector map is moved to the current mapset
281 when closing the map.
282 • delete - the temporary vector map is deleted when closing the
284 map.
285 Default value is keep. Note that temporary vector maps are not visible
286 to the user via g.list or wxGUI. They are used internally by the GRASS
287 modules and deleted automatically when GRASS session is quited.
288 GRASS_VECTOR_TMPDIR_MAPSET
290 [vectorlib]
291 By default GRASS temporary directory is located in $LOCA‐
292 TION/$MAPSET/.tmp/$HOSTNAME. If GRASS_VECTOR_TMPDIR_MAPSET is set
293 to ’0’, the temporary directory is located in TMPDIR (environmental
294 variable defined by the user or GRASS initialization script if not
295 given).
296 Important note: This variable is currently used only in vector li‐
297 brary. In other words the variable is ignored by raster or raster3d
298 library.
299 GRASS_VECTOR_TOPO_DEBUG
301 [vectorlib, v.generalize]
302 If the environment variable GRASS_VECTOR_TOPO_DEBUG exists, v.gen‐
303 eralize runs in extremely slow debug mode.
304 GRASS_WXBUNDLED
306 [wxGUI]
307 set to tell wxGUI that a bundled wxPython will be used.
308 When set, the wxGUI will not check the wxPython version, as this
309 function is incompatible with a bundled wxPython. It is up to the
310 packager to make sure that a compatible wxPython version is bun‐
311 dled.
312 GRASS_WXVERSION
314 [wxGUI]
315 set to tell wxGUI which version of wxPython to use.
316 When set, the wxGUI will select the given wxPython version. It’s
317 useful when multiple versions of wxPython are installed and the
318 user wants to run wxGUI with non-default wxPython version.
319 GRASS_XTERM
321 [lib/init/grass-xterm-wrapper, lib/init/grass-xterm-mac]
322 set to any value (e.g. rxvt, aterm, gnome-terminal, konsole) to
323 substitute ’x-terminal-emulator’ or ’xterm’. The Mac OS X app
324 startup defaults to an internal ’$GISBASE/etc/grass-xterm-mac’,
325 which emulates the necessary xterm functionality in Terminal.app.
326 GRASS_UI_TERM
328 set to any value to use the terminal based parser.
329 GRASS_VERSION
331 reports the current version number (used by R-stats interface etc);
332 should not be changed by user.
333 GRASS_NO_GLX_PBUFFERS
335 [nviz]
336 set to any value to disable the use of GLX Pbuffers.
337 GRASS_NO_GLX_PIXMAPS
339 [nviz]
340 Set to any value to disable the use of GLX Pixmaps.
341 OMP_NUM_THREADS
343 [OpenMP]
344 If OpenMP support is enabled this limits the number of threads.
345 The default is set to the number of CPUs on the system. Setting to
346 ’1’ effectively disables parallel processing.
347 TMPDIR, TEMP, TMP
349 [Various GRASS GIS commands and wxGUI]
350 The default wxGUI temporary directory is chosen from a platform-de‐
351 pendent list, but the user can control the selection of this direc‐
352 tory by setting one of the TMPDIR, TEMP or TMP environment vari‐
353 ables Hence the wxGUI uses $TMPDIR if it is set, then $TEMP, other‐
354 wise /tmp.
355 List of selected GRASS environment variables for rendering
357 [ In addition to those which are understood by specific GRASS display
358 drivers, the following variables affect rendering. ]
359 GRASS_RENDER_IMMEDIATE
361 tells the display library which driver to use; possible values:
362 cairo, png, ps, html or default.
363 Default display driver is cairo (if available) otherwise png.
364 GRASS_RENDER_WIDTH
366 defines the width of output image (default is 640).
367 GRASS_RENDER_HEIGHT
369 defines the height of output image (default is 480).
370 GRASS_RENDER_FILE
372 the name of the resulting image file.
373 GRASS_RENDER_FRAME
375 contains 4 coordinates, top,bottom,left,right (pixel values) with
376 respect to the top left corner of the output image, defining the
377 initial frame.
378 GRASS_RENDER_LINE_WIDTH
380 defines default line width.
381 GRASS_RENDER_TEXT_SIZE
383 defines default text size.
384 GRASS_RENDER_COMMAND
386 external command called by display library to render data (see ex‐
387 ample in display drivers page for details).
388 Currently only Python scripts are supported. For specific
389 driver-related variables see:
390 • Cairo display driver
392 • PNG display driver
394 • PS (Postscript) display driver
396 • HTML display driver
398 List of selected internal GRASS environment variables
400 [ These variables are intended for internal use only by the GRASS soft‐
401 ware to facilitate communication between the GIS engine, GRASS scripts,
402 and the GUI. The user should not set these in a GRASS session. They
403 are meant to be set locally for specific commands. ]
404 GRASS_OVERWRITE
406 [all modules]
407 toggles map overwrite.
408 • 0 - maps are protected (default),
410 • 1 - maps with identical names will be overwritten.
412 This variable is automatically created by g.parser so that the --over‐
413 write option will be inherited by dependent modules as the script runs.
414 Setting either the GRASS_OVERWRITE environment variable or the OVER‐
415 WRITE gisenv variable detailed below will cause maps with identical
416 names to be overwritten.
417 GRASS_VERBOSE
419 [all modules]
420 toggles verbosity level
421 • -1 - complete silence (also errors and warnings are discarded)
423 • 0 - only errors and warnings are printed
425 • 1 - progress and important messages are printed (percent com‐
427 plete)
428 • 2 - all module messages are printed
430 • 3 - additional verbose messages are printed
432 This variable is automatically created by g.parser so that the --ver‐
433 bose or --quiet flags will be inherited by dependent modules as the
434 script runs.
435 GRASS_REGION
437 [libgis]
438 override region settings, separate parameters with a ";". Format is
439 the same as in the WIND region settings file. Otherwise use is the
440 same as WIND_OVERRIDE.
441 WIND_OVERRIDE
443 [libgis]
444 it causes programs to use the specified named region (created with
445 e.g. g.region save=...) to be used as the current region, instead
446 of the region from the WIND file.
447 This allows programs such as the GUI to run external commands on an
448 alternate region without having to modify the WIND file then change
449 it back afterwards.
450
452 [ Use g.gisenv to get/set/unset/change them ]
453 DEBUG
455 [entire GRASS]
456 sets level of debug message output (0: no debug messages)
457 g.gisenv set=DEBUG=0
458 WX_DEBUG
460 [wxGUI]
461 sets level of debug message output for wxGUI (0: no debug messages,
462 1-5 debug levels)
463 GISDBASE
465 initial database
466 GIS_LOCK
468 lock ID to prevent parallel GRASS use,
469 process id of the start-up shell script
470 GUI
472 See GRASS_GUI environmental variable for details.
473 LOCATION
475 full path to location directory
476 LOCATION_NAME
478 initial location name
479 MAPSET
481 initial mapset
482 MEMORYMB
484 [entire GRASS with focus on raster related data processing]
485 sets the maximum memory to be used (in MB), i.e. the cache size for
486 raster rows
487 # set to 6 GB (default: 300 MB)
488 g.gisenv set="MEMORYMB=6000"
489 NPROCS
491 sets the number of threads for parallel computing
492 # set to use 12 threads (default: 1)
493 g.gisenv set="NPROCS=12"
494 OVERWRITE
496 [all modules]
497 toggles map overwrite.
498 • 0 - maps are protected (default),
500 • 1 - maps with identical names will be overwritten.
502 This variable is automatically created by g.parser so that the --over‐
503 write option will be inherited by dependent modules as the script runs.
504 Setting either the GRASS_OVERWRITE environment variable or the OVER‐
505 WRITE gisenv variable detailed below will cause maps with identical
506 names to be overwritten.
507
509 $HOME/.grass8/rc
510 stores the GRASS gisenv variables (not shell environment variables)
511 $HOME/.grass8/bashrc
513 stores the shell environment variables (Bash only)
514 $HOME/.grass8/env.bat
516 stores the shell environment variables (MS Windows only)
517 $HOME/.grass8/login
519 stores the DBMI passwords in this hidden file. Only the file owner
520 can access this file.
521 $HOME/GIS_ERROR_LOG
523 if this file exists then all GRASS error and warning messages are
524 logged here. Applies to current user. To generate the file, use:
525 touch $HOME/GIS_ERROR_LOG
526 See also GIS_ERROR_LOG variable. Note: On MS Windows the files are
527 stored in %APPDATA%.
528
530 g.gisenv, g.parser
531 Main index | Topics index | Keywords index | Graphical index | Full in‐
533 dex
534 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
536GRASS 8.2.1 variables(1)