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