1grass(1)                    GRASS GIS User's Manual                   grass(1)
2
3
4

GRASS startup program

SYNOPSIS

7       grass  [-h  |  -help | --help] [-v | --version] | [-c | -c geofile | -c
8       EPSG:code[:datum_trans]] | -e | -f |  [--text  |  --gtext  |  --gui]  |
9       --config  | [--tmp-location | --tmp-mapset] [[[<GISDBASE>/]<LOCATION>/]
10       <MAPSET>] [--exec EXECUTABLE]
11
12   Flags:
13       -h | -help | --help
14           Prints a brief usage message and exits
15
16       -v | --version
17           Prints the version of GRASS and exits
18
19       -c
20           Creates new GRASS unprojected location in specified GISDBASE
21
22       -c geofile
23           Creates new GRASS projected location in specified GISDBASE based on
24           georeferenced file
25
26       -c EPSG:code
27           Creates  new  GRASS  projected  location in specified GISDBASE with
28           given EPSG code
29
30       -c EPSG:code:datum_trans
31           Creates new GRASS projected location  in  specified  GISDBASE  with
32           given EPSG code and datum transform parameters
33
34       -e
35           Exit after creation of location or mapset. Only with -c flag
36
37       -f
38           Forces  removal  of  .gislock if exists (use with care!). Only with
39           --text flag
40
41       --text
42           Indicates that Text-based User Interface should be used (skip  wel‐
43           come screen)
44
45       --gtext
46           Indicates  that Text-based User Interface should be used (show wel‐
47           come screen)
48
49       --gui
50           Indicates that Graphical User Interface (wxGUI) should be used
51
52       --config
53           Prints GRASS configuration parameters (options: arch,  build,  com‐
54           piler, date, path, python_path, revision, svn_revision, version)
55
56       --exec EXECUTABLE
57           Execute GRASS module or script. The provided executable will be ex‐
58           ecuted in a GRASS GIS non-interactive session.
59
60       --tmp-location
61           Run using a temporary location which is created based on the  given
62           coordinate reference system and deleted at the end of the execution
63           (use with the --exec flag).  The active mapset will be  the  PERMA‐
64           NENT mapset.
65
66       --tmp-mapset
67           Run  using a temporary mapset which is created in the specified lo‐
68           cation and deleted at the end of the execution (use with the --exec
69           flag).
70
71   Parameters:
72       GISDBASE
73           Initial  database  directory which should be a fully qualified path
74           (e.g., /usr/local/share/grassdata)
75
76       LOCATION
77           Initial location directory which is a subdirectory of GISDBASE
78
79       MAPSET
80           Initial mapset directory which is a subdirectory of LOCATION  Note:
81           These parameters must be specified in one of the following ways:
82               MAPSET
83               LOCATION/MAPSET
84               GISDBASE/LOCATION/MAPSET
85

DESCRIPTION

87       This  command  is  used  to launch GRASS GIS. It will parse the command
88       line arguments and then initialize GRASS for the user. Since GRASS mod‐
89       ules require a specific environment, this program must be called before
90       any other GRASS module can run. The command line arguments are optional
91       and  provide the user with a method to indicate the desired user inter‐
92       face, as well as the desired mapset to work on.
93
94       The startup program will remember both the desired user  interface  and
95       mapset.  Thus, the next time the user runs GRASS, typing grass (without
96       any options) will start GRASS with the previous settings for  the  user
97       interface and mapset selected.
98
99       If  you  specify  a  graphical user interface (--gui) the grass program
100       will try to verify that the system you specified exists  and  that  you
101       can access it successfully. If any of these checks fail then grass will
102       automatically switch back to the text user interface mode.
103
104   Running non-interactive jobs
105       The --exec flag can run an executable  on  path,  GRASS  module,  or  a
106       script.   All are executed as a subprocess and any additional arguments
107       are passed to it.  A script needs to be specified by full  or  relative
108       path  and  on  unix-likes  systems,  the script file must have its exe‐
109       cutable bit set. Calling the interpreter (e.g., python)  and  providing
110       the  script as a parameter is possible, too.  When it is finished GRASS
111       will automatically exit using the return code given by the  subprocess.
112       Although the execution itself is non-interactive (no GUI or shell), the
113       subprocess itself can be interactive if that is what the user requires.
114
115   Config flag
116       The flag --config option prints GRASS GIS configuration and version pa‐
117       rameters, with the options:
118
119arch: system architecture (e.g., x86_64-pc-linux-gnu)
120
121build:   (e.g.,   ./configure   --with-cxx   --enable-largefile
122               --with-proj [...])
123
124compiler: (e.g., gcc)
125
126date: (e.g., Tue Mar 31 20:34:57 2020 +0200)
127
128path: (e.g., /usr/lib64/grass)
129
130python_path: (e.g., /usr/lib64/grass/etc/python)
131
132revision: (e.g., 745ee7ec9)
133
134svn_revision: (e.g., 062bffc8)
135
136version: (e.g., 8.2.0dev)
137

SAMPLE DATA

139       The GRASS GIS project provides several free sample geospatial  datasets
140       as   ready-to-use   locations.   They  are  available  to  download  at
141       https://grass.osgeo.org/download/sample-data/.   The  "North   Carolina
142       data  set"  is  a modern package of geospatial data from North Carolina
143       (USA), and it includes raster, vector, LiDAR and satellite  data.  This
144       is  the most extensively used data set in the documentation and the ex‐
145       amples throughout the user manual pages are based upon it.
146

ENVIRONMENT VARIABLES

148       A number of environment variables are available at GRASS startup to as‐
149       sist  with  automation  and  customization. Most users will not need to
150       bother with these.
151
152       In addition to these shell environment variables GRASS maintains a num‐
153       ber  of  GIS  environment  variables in the $HOME/.grass8/rc file. User
154       changes to this file will be read during the next startup of GRASS.  If
155       this  file  becomes corrupted the user may edit it by hand or remove it
156       to start afresh.  See the list of implemented GRASS variables for  more
157       information.  The rest of this help page will only consider shell envi‐
158       ronment variables.
159
160       Note that you will need to set these variables  using  the  appropriate
161       method  required  for the UNIX shell that you use (e.g. in a Bash shell
162       you must export the variables for them to propagate).
163
164   User Interface Environment Variable
165       The grass program will check for the existence of an environment  vari‐
166       able  called  GRASS_GUI  which indicates the type of user interface for
167       GRASS to use. If this variable is not set when grass is  run,  then  it
168       will  be  created  and  then saved in the $HOME/.grass8/rc file for the
169       next time GRASS is run. It can be set to text, gtext or gui.
170
171       There is an order of precedence in the way grass  determines  the  user
172       interface  to  use.  The following is the hierarchy from highest prece‐
173       dence to lowest.
174
175       1      Command line argument
176
177       2      Environment variable GRASS_GUI
178
179       3      Value set in $HOME/.grass8/rc (GUI)
180
181       4      Default value - gui
182
183   Python Environment Variables
184       If you choose to use wxGUI interface, then the GRASS_PYTHON environment
185       variable can be used to override your system default python command.
186
187       Suppose  for  example  your system has Python 3.6 installed and you in‐
188       stall a personal version of the Python 3.8  binaries  under  $HOME/bin.
189       You  can use the above variables to have GRASS use the Python 3.8 bina‐
190       ries instead.
191          GRASS_PYTHON=python3.8
192
193   Addon Path to Extra User Scripts
194       This environment variable allows the user to extend the  GRASS  program
195       search  paths  to  include locally developed/installed GRASS modules or
196       user scripts.
197          GRASS_ADDON_PATH=/usr/mytools
198          GRASS_ADDON_PATH=/usr/mytools:/usr/local/othertools
199
200       In this example above path(s) would be added to the standard GRASS path
201       environment.
202
203   Addon Base for Extra Local GRASS Addon Modules
204       This  environment  variable allows the user to extend the GRASS program
205       search paths to include locally installed (see g.extension for details)
206       GRASS  Addon  modules which are not distributed with the standard GRASS
207       release.
208          GRASS_ADDON_BASE=/usr/grass-addons
209
210       In this example above path would be added to the  standard  GRASS  path
211       environment.
212
213       If  not  defined by user, this variable is set by GRASS startup program
214       to $HOME/.grass8/addons on GNU/Linux  and  %APPDATA%\Roaming\GRASS8\ad‐
215       dons on MS Windows.
216
217   HTML Browser Variable
218       The  GRASS_HTML_BROWSER environment variable allows the user to set the
219       HTML web browser to use for displaying help pages.
220

EXAMPLES

222       The following are some examples of how you could start GRASS
223
224       grass
225           Start GRASS using the default user  interface.  The  user  will  be
226           prompted to choose the appropriate location and mapset.
227
228       grass --gui
229           Start  GRASS  using  the graphical user interface. The user will be
230           prompted to choose the appropriate location and mapset.
231
232       grass --text
233           Start GRASS using the text-based user interface. Appropriate  loca‐
234           tion  and  mapset must be set by environmental variables (see exam‐
235           ples below) otherwise taken from the last GRASS session.
236
237       grass --gtext
238           Start GRASS using the text-based user interface. The user  will  be
239           prompted to choose the appropriate location and mapset.
240
241       grass $HOME/grassdata/spearfish70/user1
242           Start  GRASS  using  the  default  user interface and automatically
243           launch into the given mapset, bypassing the mapset selection menu.
244
245       grass --gui -
246           Start GRASS using the graphical user interface and  try  to  obtain
247           the location and mapset from environment variables.
248
249       grass -c EPSG:4326 $HOME/grassdata/mylocation
250           Creates  a  new GRASS location with EPSG code 4326 (latitude-longi‐
251           tude, WGS84) in the specified GISDBASE
252
253       grass -c EPSG:5514:3 $HOME/grassdata/mylocation
254           Creates a new GRASS location with EPSG code 5514 (S-JTSK  /  Krovak
255           East  North  -  SJTSK) with datum transformation parameters used in
256           Czech Republic in the specified GISDBASE
257
258       grass -c XY $HOME/grassdata/gnomonic --exec g.proj -c proj4=’+proj=gnom
259       +lat_0=90 +lon_0=-50’
260           Creates  a  new  GRASS  location from PROJ definition string (here:
261           gnomonic) in the specified GISDBASE
262
263       grass -c myvector.shp $HOME/grassdata/mylocation
264           Creates a new GRASS location based on georeferenced Shapefile
265
266       grass -c myraster.tif $HOME/grassdata/mylocation
267           Creates a new GRASS location based on georeferenced GeoTIFF file
268
269   Batch jobs with the exec interface
270       Creating a new Location based on a geodata file’s projection  (-c)  and
271       exit (-e) immediately:
272       grass -c elevation.tiff -e /path/to/grassdata/test1/
273       Linking external raster data to PERMANENT Mapset:
274       grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
275       grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
276       Get statistics for one raster map:
277       grass /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
278       Compare the rasters visually:
279       grass /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
280
281   Execution of shell and Python scripts instead of single commands
282       A  sequence  of  commands can be bundled in a script and executed using
283       the exec interface.
284
285       Shell script example: the command to execute a shell script might be:
286       grass /path/to/grassdata/test1/PERMANENT/ --exec sh test.sh
287       A very simple bash script ("test.sh") may look like this:
288       #!/bin/bash
289       g.region -p
290       g.list type=raster
291       r.info elevation
292
293       Python script example: the command to execute a Python script might be:
294       grass /path/to/grassdata/test1/PERMANENT/ --exec python test.py
295       A very simple Python script ("test.py") may look like this:
296       #!/usr/bin/env python3
297       # import GRASS Python bindings (see also pygrass)
298       import grass.script as gs
299       import grass.script.setup as gsetup
300       gs.message(’Current GRASS GIS 8 environment:’)
301       print(gs.gisenv())
302       gs.message(’Available raster maps:’)
303       for raster in gs.list_strings(type=’raster’):
304           print(raster)
305       gs.message(’Available vector maps:’)
306       for vector in gs.list_strings(type=’vector’):
307           print(vector)
308
309   Using temporary location
310       Creating a new temporary location based on a georeferenced file’s  pro‐
311       jection  coordinate  reference system (CRS) and simultaneously starting
312       computation in a shell script:
313       grass --tmp-location elevation.tiff --exec test.sh
314       The same, but using an EPSG code and a Python script:
315       grass --tmp-location EPSG:3358 --exec test.py
316       Finally, for special cases, we can create an XY  location  without  any
317       CRS:
318       grass --tmp-location XY --exec test.py
319       Temporary  location  is automatically deleted after computation, so the
320       script is expected to export, link or  otherwise  preserve  the  output
321       data before ending.
322
323       A  single  command  can be also executed, e.g. to examine properties of
324       the temporary location:
325       grass --tmp-location EPSG:3358 --exec g.proj -p
326       A temporary XY location with single command is  useful,  e.g.  to  show
327       help text of a module:
328       grass --tmp-location XY --exec r.neighbors --help
329
330   Using temporary mapset
331       A  single command can be executed, e.g., to examine properties of a lo‐
332       cation (here using the NC SPM sample location):
333       grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec g.proj -p
334       Computation in a Python script can be executed in the same way:
335       grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py
336       Additional parameters are just passed to the script, so we can run  the
337       script  with  different sets of parameters (here 5, 8 and 3, 9) in dif‐
338       ferent temporary mapsets which is good for parallel processing.
339       grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 5 8
340       grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 3 9
341       The same applies to Bash scripts (and other scripts  supported  on  you
342       platform):
343       grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.sh 5 8
344       The temporary mapset is automatically deleted after computation, so the
345       script is expected to export, link or  otherwise  preserve  the  output
346       data before ending.
347
348   Troubleshooting
349       Importantly,  to avoid an "[Errno 8] Exec format error" there must be a
350       shebang line at the top of the script (like #!/bin/sh, #!/bin/bash,  or
351       #!/usr/bin/env python3) indicating which interpreter to be used for the
352       script. The script file must have its executable bit set.
353

CAVEAT

355       If you start GRASS using the wxGUI interface you  must  have  a  python
356       command  in  your  $PATH  variable.  That is, the command must be named
357       python and not something like python3.6. Rarely some  Python  installa‐
358       tions  do  not create a python command. In these cases you can override
359       python by GRASS_PYTHON environmental variable.
360
361       Furthermore, if you have more than one  version  of  Python  installed,
362       make  sure  that  the  version  you  want  to  use with GRASS is set by
363       GRASS_PYTHON environmental variable.
364

SEE ALSO

366       List of GRASS environment variables
367
368       GRASS GIS Web site
369       GRASS GIS User Wiki
370       GRASS GIS Bug Tracker
371       GRASS GIS 8 Programmer’s Manual
372

AUTHORS (of this page)

374       Justin Hickey
375       Markus Neteler
376       Hamish Bowman
377       Martin Landa, Czech Technical University in Prague, Czech Republic
378
379       Main index | Topics index | Keywords index | Graphical index | Full in‐
380       dex
381
382       © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
383
384
385
386GRASS 8.2.0                                                           grass(1)
Impressum