1variables(1)                  Grass User's Manual                 variables(1)
2
3
4

GRASS variables and environment variables

6       There are two types of variables:
7
8           ·   shell environment variables,
9
10           ·   GRASS gisenv variables.
11       There are a number of shell environment variable groups:
12
13           ·   variables for rendering
14
15           ·   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

Setting shell environment variables

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
29           ·   To get personal BASH shell definitions (aliases, color  listing
30               option, ...)  into GRASS, store them in:
31               $HOME/.grass7/bashrc
32
33           ·   To  get  personal CSH shell definitions (aliases, color listing
34               option, ...)  into GRASS, store them in:
35               $HOME/.grass7/cshrc
36

Setting GRASS gisenv variables

38       Use g.gisenv within GRASS. This permanently predefines GRASS  variables
39       in the .grass7/rc file.
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
45       If the user just specifies a variable name, it defaults  to  get  mode.
46       For example:
47       g.gisenv MAPSET
48       PERMANENT
49

List of selected (GRASS related) shell environment variables

51       [ To be set from the terminal shell or startup scripts ]
52
53       GISBASE
54           directory  where  GRASS  lives.  This  is  set automatically by the
55           startup script.
56
57       GISRC
58           name of .grass7/rc file. Defines the system wide value while  in  a
59           GRASS session.
60
61       GRASS_ADDON_PATH
62           [grass startup script, g.extension]
63           specifies  additional  path(s) containing local and/or custom GRASS
64           modules extra to the standard distribution.
65
66       GRASS_ADDON_BASE
67           [grass startup script]
68           allows specifying additional GISBASE for local GRASS modules  (nor‐
69           mally  installed  as  GRASS  Addons by g.extension module) extra to
70           standard   distribution.    The    default    on    GNU/Linux    is
71           $HOME/.grass7/addons, on MS Windows $APPDATA\GRASS7\addons.
72
73       GRASS_ADDON_ETC
74           [libgis, g.findetc]
75           specify  paths  where support files (etc/) may be found external to
76           standard distribution.
77
78       GRASS_BATCH_JOB
79           defines the name (path) of a shell script to be processed as  batch
80           job.
81
82       GRASS_COMPRESSOR
83           [libraster]
84           the  compression  method  for  new  raster maps can be set with the
85           environment variable GRASS_COMPRESSOR. Supported methods  are  RLE,
86           ZLIB,  LZ4,  BZIP2,  and  ZSTD.  The  default  is ZLIB which can be
87           changed with e.g. GRASS_COMPRESSOR=ZSTD
88
89       GRASS_DB_ENCODING
90           [various modules, wxGUI]
91           encoding  for  vector  attribute  data  (utf-8,  ascii,  iso8859-1,
92           koi8-r)
93
94       GIS_ERROR_LOG
95           If  set,  GIS_ERROR_LOG should be the absolute path to the log file
96           (a relative path will be interpreted relative to the process’  cwd,
97           not  the  cwd  at the point the user set the variable). If not set,
98           $HOME/GIS_ERROR_LOG is used instead. The file will only be used  if
99           it already exists.
100
101       GRASS_ERROR_MAIL
102           set to any value to send user mail on an error or warning that hap‐
103           pens while stderr is being redirected.
104
105       GRASS_FONT
106           [display drivers]
107           specifies the font  as  either  the  name  of  a  font  from  $GIS‐
108           BASE/etc/fontcap   (or   alternative   fontcap  file  specified  by
109           GRASS_FONT_CAP), or alternatively the full path to a FreeType  font
110           file.
111
112       GRASS_ENCODING
113           [display drivers]
114           the encoding to be assumed for text which is drawn using a freetype
115           font; may be any encoding know to iconv.
116
117       GRASS_FONT_CAP
118           [g.mkfontcap, d.font, display drivers]
119           specifies an alternative location (to $GISBASE/etc/fontcap) for the
120           font configuration file.
121
122       GRASS_FULL_OPTION_NAMES
123           [parser]
124           Generates a warning if GRASS_FULL_OPTION_NAMES is set (to anything)
125           and a found string is not an exact match for the given string.
126
127       GRASS_GUI
128           either text (text user interface), gtext (text user interface  with
129           GUI  welcome  screen),  or gui (graphical user interface) to define
130           non-/graphical startup. Can also specify the name  of  the  GUI  to
131           use,  e.g. wxpython (wxGUI). Also exists as a GRASS gisenv variable
132           (see below). If this shell variable exists  at  GRASS  startup,  it
133           will  determine  the  GUI  used.  If it is not defined startup will
134           default to the last GUI used.
135
136       GRASS_HTML_BROWSER
137           [init.sh, wxgui]
138           defines name of HTML browser. For most platforms this should be  an
139           executable in your PATH, or the full path to an executable.
140           Mac  OS  X  runs applications differently from the CLI.  Therefore,
141           GRASS_HTML_BROWSER should be the application’s signature, which  is
142           a  domain-like  name, just reversed, i.e. com.apple.Safari. To find
143           an application’s signature, type the following in a Terminal  (fill
144           in  the path to the application you are interested in, for example:
145           /Applications/Safari.app):
146           grep  -A   1   "CFBundleIdentifier"   /path/to/application.app/Con‐
147           tents/Info.plist
148           The  signature  is  the  <string>  following the <key>, without the
149           bracketing <string> tags.
150
151       GRASS_INT_ZLIB
152           [libraster]
153           if the environment variable GRASS_INT_ZLIB exists and has the value
154           0,  new  compressed  integer  (CELL  type) raster maps will be com‐
155           pressed using RLE compression.
156           If the variable doesn’t exist, or the value is non-zero, zlib  com‐
157           pression  will be used instead. Such rasters will have a compressed
158           value of 2 in the cellhd file.
159           Obviously, decompression is controlled by the  raster’s  compressed
160           value, not the environment variable.
161
162       GRASS_ZLIB_LEVEL
163           [libgis]
164           if  the  environment variable GRASS_ZLIB_LEVEL exists and its value
165           can be parsed as an integer, it determines  the  compression  level
166           used when new compressed raster maps are compressed using zlib com‐
167           pression. This applies  to  all  raster  map  types  (CELL,  FCELL,
168           DCELL).
169           Valid  zlib compression levels are -1 to 9. The GRASS_ZLIB_LEVEL=-1
170           corresponds   to   the   zlib   default   value   (equivalent    to
171           GRASS_ZLIB_LEVEL=6).  Often  GRASS_ZLIB_LEVEL=1 gives the best com‐
172           promise between speed and compression.
173           If the variable doesn’t exist, or the value cannot be parsed as  an
174           integer, zlib’s default compression level 6 will be used.
175
176       GRASS_MESSAGE_FORMAT
177           [various modules, wxGUI]
178           it may be set to either
179
180           ·   standard  - sets percentage output and message formatting style
181               to standard formatting,
182
183           ·   gui - sets percentage output and message  formatting  style  to
184               GUI formatting,
185
186           ·   silent - disables percentage output and error messages,
187
188           ·   plain  - sets percentage output and message formatting style to
189               ASCII output without rewinding control characters.
190
191       GRASS_MOUSE_BUTTON
192           [various modules]
193           swaps mouse buttons for two-button or left-handed mice.  Its  value
194           has three digits 1, 2, and 3, which represent default left, middle,
195           and right buttons respectively. Setting to 132 will swap middle and
196           right  buttons. Note that this variable should be set before a dis‐
197           play driver is initialized (e.g., d.mon x0).
198
199       GRASS_PAGER
200           [various modules]
201           it may be set to either less, more, or cat.
202
203       GRASS_PERL
204           [used during install process for generating man pages]
205           set Perl with path.
206
207       GRASS_SKIP_MAPSET_OWNER_CHECK
208           By default it is not possible to work with  MAPSETs  that  are  not
209           owned by current user. Setting this variable to any non-empty value
210           allows the check to be skipped.
211
212       GRASS_SH
213           [shell scripts on Windows]
214           path to bourne shell interpreter used to run shell scripts.
215
216       GRASS_SIGSEGV_ON_ERROR
217           Raise SIGSEGV if an error occurs]
218           This variable can  be  set  for  debugging  purpose.  The  call  of
219           G_fatal_error()  will  end  in a segmentation violation. GDB can be
220           used to trace the source of the error.
221
222       GRASS_PYTHON
223           [wxGUI, Python Ctypes]
224           set to override Python executable.
225           On Mac OS X this should be the pythonw executable for the wxGUI  to
226           work.
227
228       GRASS_VECTOR_LOWMEM
229           [vectorlib]
230           If the environment variable GRASS_VECTOR_LOWMEM exists, memory con‐
231           sumption will be reduced  when  building  vector  topology  support
232           structures. Recommended for creating large vectors.
233
234       GRASS_VECTOR_OGR
235           [vectorlib, v.external.out]
236           If the environment variable GRASS_VECTOR_OGR exists and vector out‐
237           put format defined by v.external.out is PostgreSQL, vector data  is
238           written  by OGR data provider even the native PostGIS data provider
239           is available.
240
241       GRASS_VECTOR_EXTERNAL_IMMEDIATE
242           [vectorlib, v.external.out]
243           If the environment variable GRASS_VECTOR_EXTERNAL_IMMEDIATE  exists
244           and  vector  output format defined by v.external.out is non-native,
245           vector features are written to output external  datasource  immedi‐
246           ately.  By default, the vector library writes output data to a tem‐
247           porary vector map in native format and when closing  the  map,  the
248           features  are  transferred  to output external datasource. Note: if
249           output vector format is topological PostGIS format, then the vector
250           library  writes  features  immediately  to output database (in this
251           case GRASS_VECTOR_EXTERNAL_IMMEDIATE is ignored).
252
253       GRASS_VECTOR_EXTERNAL_IGNORE
254           [vectorlib]
255           If the environment  variable  GRASS_VECTOR_EXTERNAL_IGNORE  exists,
256           output vector format defined by v.external.out is ignored. The for‐
257           mat is always native.
258
259       GRASS_VECTOR_TEMPORARY
260           [vectorlib]
261           If the environment variable  GRASS_VECTOR_TEMPORARY  exists,  GRASS
262           vector  library  will  operate on temporary vector maps. New vector
263           maps  will  be  created  in  temporary  directory  (see  GRASS_VEC‐
264           TOR_TMPDIR_MAPSET  variable), existing vector maps will be read (if
265           found) also from this directory. It may be set to either:
266
267           ·   keep - the temporary vector map is not deleted when closing the
268               map.
269
270           ·   move  - the temporary vector map is moved to the current mapset
271               when closing the map.
272
273           ·   delete - the temporary vector map is deleted when  closing  the
274               map.
275       Default value is keep.  Note that temporary vector maps are not visible
276       to the user via g.list or wxGUI. They are used internally by the  GRASS
277       modules and deleted automatically when GRASS session is quited.
278
279       GRASS_VECTOR_TMPDIR_MAPSET
280           [vectorlib]
281           By   default   GRASS  temporary  directory  is  located  in  $LOCA‐
282           TION/$MAPSET/.tmp/$HOSTNAME. If GRASS_VECTOR_TMPDIR_MAPSET  is  set
283           to ’0’, the temporary directory is located in TMPDIR (environmental
284           variable defined by the user or GRASS initialization script if  not
285           given).
286           Important  note:  This  variable  is  currently used only in vector
287           library. In other words  the  variable  is  ignored  by  raster  or
288           raster3d library.
289
290       GRASS_VECTOR_TOPO_DEBUG
291           [vectorlib, v.generalize]
292           If  the environment variable GRASS_VECTOR_TOPO_DEBUG exists, v.gen‐
293           eralize runs in extremely slow debug mode.
294
295       GRASS_WXBUNDLED
296           [wxGUI]
297           set to tell wxGUI that a bundled wxPython will be used.
298           When set, the wxGUI will not check the wxPython  version,  as  this
299           function  is incompatible with a bundled wxPython.  It is up to the
300           packager to make sure that a compatible wxPython  version  is  bun‐
301           dled.
302
303       GRASS_WXVERSION
304           [wxGUI]
305           set to tell wxGUI which version of wxPython to use.
306           When  set,  the  wxGUI will select the given wxPython version. It’s
307           useful when multiple versions of wxPython  are  installed  and  the
308           user wants to run wxGUI with non-default wxPython version.
309
310       GRASS_XTERM
311           [lib/init/grass-xterm-wrapper, lib/init/grass-xterm-mac]
312           set  to  any  value  (e.g. rxvt, aterm, gnome-terminal, konsole) to
313           substitute ’x-terminal-emulator’ or  ’xterm’.  The  Mac  OS  X  app
314           startup  defaults  to  an  internal ’$GISBASE/etc/grass-xterm-mac’,
315           which emulates the necessary xterm functionality in Terminal.app.
316
317       GRASS_UI_TERM
318           set to any value to use the terminal based parser.
319
320       GRASS_VERSION
321           reports the current version number (used by R-stats interface etc);
322           should not be changed by user.
323
324       GRASS_NO_GLX_PBUFFERS
325           [nviz]
326           set to any value to disable the use of GLX Pbuffers.
327
328       GRASS_NO_GLX_PIXMAPS
329           [nviz]
330           Set to any value to disable the use of GLX Pixmaps.
331
332       OMP_NUM_THREADS
333           [OpenMP]
334           If  OpenMP  support  is  enabled this limits the number of threads.
335           The default is set to the number of CPUs on the system.  Setting to
336           ’1’ effectively disables parallel processing.
337
338       TMPDIR, TEMP, TMP
339           [Various GRASS GIS commands and wxGUI]
340           The  default  wxGUI  temporary  directory  is  chosen  from a plat‐
341           form-dependent list, but the user can control the selection of this
342           directory  by  setting  one  of the TMPDIR, TEMP or TMP environment
343           variables Hence the wxGUI uses $TMPDIR if it is  set,  then  $TEMP,
344           otherwise /tmp.
345
346   List of selected GRASS environment variables for rendering
347       [  In  addition to those which are understood by specific GRASS display
348       drivers, the following variables affect rendering. ]
349
350       GRASS_RENDER_IMMEDIATE
351           tells the display library which driver  to  use;  possible  values:
352           cairo, png, ps, html or default
353           Default display driver is cairo (if available) otherwise png.
354
355       GRASS_RENDER_WIDTH
356           defines the width of output image (default is 640).
357
358       GRASS_RENDER_HEIGHT
359           defines the height of output image (default is 480).
360
361       GRASS_RENDER_FILE
362           the name of the resulting image file.
363
364       GRASS_RENDER_FRAME
365           contains  4  coordinates, top,bottom,left,right (pixel values) with
366           respect to the top left corner of the output  image,  defining  the
367           initial frame.
368
369       GRASS_RENDER_LINE_WIDTH
370           defines default line width.
371
372       GRASS_RENDER_TEXT_SIZE
373           defines default text size.
374
375       GRASS_RENDER_COMMAND
376           external  command  called  by  display  library to render data (see
377           example in display drivers page for details).
378           Currently  only  Python  scripts  are  supported.    For   specific
379           driver-related variables see:
380
381           ·   Cairo display driver
382
383           ·   PNG display driver
384
385           ·   PS (Postscript) display driver
386
387           ·   HTML display driver
388
389   List of selected internal GRASS environment variables
390       [ These variables are intended for internal use only by the GRASS soft‐
391       ware to facilitate communication between the GIS engine, GRASS scripts,
392       and  the  GUI.   The user should not set these in a GRASS session. They
393       are meant to be set locally for specific commands. ]
394
395       GRASS_OVERWRITE
396           [all modules]
397           toggles map overwrite.
398
399           ·   0 - maps are protected (default),
400
401           ·   1 - maps with identical names will be overwritten.
402       This variable is automatically created by g.parser so that the  --over‐
403       write option will be inherited by dependent modules as the script runs.
404       Setting either the GRASS_OVERWRITE environment variable  or  the  OVER‐
405       WRITE  gisenv  variable  detailed  below will cause maps with identical
406       names to be overwritten.
407
408       GRASS_VERBOSE
409           [all modules]
410           toggles verbosity level
411
412           ·   -1 - complete silence (also errors and warnings are discarded)
413
414           ·   0 - only errors and warnings are printed
415
416           ·   1 - progress and important messages are printed  (percent  com‐
417               plete)
418
419           ·   2 - all module messages are printed
420
421           ·   3 - additional verbose messages are printed
422       This  variable  is automatically created by g.parser so that the --ver‐
423       bose or --quiet flags will be inherited by  dependent  modules  as  the
424       script runs.
425
426       GRASS_REGION
427           [libgis]
428           override region settings, separate parameters with a ";". Format is
429           the same as in the WIND region settings file. Otherwise use is  the
430           same as WIND_OVERRIDE.
431
432       WIND_OVERRIDE
433           [libgis]
434           it  causes programs to use the specified named region (created with
435           e.g. g.region save=...) to be used as the current  region,  instead
436           of the region from the WIND file.
437           This allows programs such as the GUI to run external commands on an
438           alternate region without having to modify the WIND file then change
439           it back afterwards.
440

List of selected GRASS gisenv variables

442       [ Use g.gisenv to get/set/unset/change them ]
443
444       DEBUG
445           [entire GRASS]
446           sets level of debug message output (0: no debug messages)
447           g.gisenv set=DEBUG=0
448
449       WX_DEBUG
450           [wxGUI]
451           sets level of debug message output for wxGUI (0: no debug messages,
452           1-5 debug levels)
453
454       GISDBASE
455           initial database
456
457       GIS_LOCK
458           lock ID to prevent parallel GRASS use,
459           process id of the start-up shell script
460
461       GUI
462           See GRASS_GUI environmental variable for details.
463
464       LOCATION
465           full path to location directory
466
467       LOCATION_NAME
468           initial location name
469
470       MAPSET
471           initial mapset
472
473       OVERWRITE
474           [all modules]
475           toggles map overwrite.
476
477           ·   0 - maps are protected (default),
478
479           ·   1 - maps with identical names will be overwritten.
480       This variable is automatically created by g.parser so that the  --over‐
481       write option will be inherited by dependent modules as the script runs.
482       Setting either the GRASS_OVERWRITE environment variable  or  the  OVER‐
483       WRITE  gisenv  variable  detailed  below will cause maps with identical
484       names to be overwritten.
485
487       $HOME/.grass7/rc
488           stores the GRASS gisenv variables (not shell environment variables)
489
490       $HOME/.grass7/bashrc
491           stores the shell environment variables (Bash only)
492
493       $HOME/.grass7/env.bat
494           stores the shell environment variables (MS Windows only)
495
496       $HOME/.grass7/login
497           stores the DBMI passwords in this hidden file.  Only the file owner
498           can access this file.
499
500       $HOME/GIS_ERROR_LOG
501           if  this  file exists then all GRASS error and warning messages are
502           logged here. Applies to current user. To generate  the  file,  use:
503           touch $HOME/GIS_ERROR_LOG
504           See also GIS_ERROR_LOG variable.  Note: On MS Windows the files are
505           stored in %APPDATA%.
506

SEE ALSO

508        g.gisenv, g.parser
509
510       Last changed: $Date: 2018-06-07 16:45:42 +0200 (Thu, 07 Jun 2018) $
511
512       Main index | Topics index | Keywords index |  Graphical  index  |  Full
513       index
514
515       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
516
517
518
519GRASS 7.6.0                                                       variables(1)
Impressum