---
name: g.region
description: Manages the boundary definitions for the geographic region.
keywords: [ general, settings, computational region, extent, resolution, level1 ]
---

# g.region

Manages the boundary definitions for the geographic region.

=== "Command line"

    **g.region**
    [**-dsplectwmn3bgfauo**]
    [**region**=*name*]
    [**raster**=*name* [,*name*,...]]
    [**raster_3d**=*name*]
    [**vector**=*name* [,*name*,...]]
    [**n**=*value*]
    [**s**=*value*]
    [**e**=*value*]
    [**w**=*value*]
    [**t**=*value*]
    [**b**=*value*]
    [**rows**=*value*]
    [**cols**=*value*]
    [**res**=*value*]
    [**res3**=*value*]
    [**nsres**=*value*]
    [**ewres**=*value*]
    [**nsres3**=*value*]
    [**ewres3**=*value*]
    [**tbres**=*value*]
    [**zoom**=*name*]
    [**align**=*name*]
    [**grow**=*value*]
    [**save**=*name*]
    **format**=*name*
    [**--overwrite**]
    [**--verbose**]
    [**--quiet**]
    [**--qq**]
    [**--ui**]

    Example:

    ```sh
    g.region region=name format=plain
    ```

=== "Python (grass.tools)"

    *grass.tools.Tools.g_region*(**region**=*None*,
        **raster**=*None*,
        **raster_3d**=*None*,
        **vector**=*None*,
        **n**=*None*,
        **s**=*None*,
        **e**=*None*,
        **w**=*None*,
        **t**=*None*,
        **b**=*None*,
        **rows**=*None*,
        **cols**=*None*,
        **res**=*None*,
        **res3**=*None*,
        **nsres**=*None*,
        **ewres**=*None*,
        **nsres3**=*None*,
        **ewres3**=*None*,
        **tbres**=*None*,
        **zoom**=*None*,
        **align**=*None*,
        **grow**=*None*,
        **save**=*None*,
        **format**=*"plain"*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    tools = Tools()
    tools.g_region(region="name", format="json")
    ```

    This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

=== "Python (grass.script)"

    *grass.script.parse_command*("***g.region***",
        **region**=*None*,
        **raster**=*None*,
        **raster_3d**=*None*,
        **vector**=*None*,
        **n**=*None*,
        **s**=*None*,
        **e**=*None*,
        **w**=*None*,
        **t**=*None*,
        **b**=*None*,
        **rows**=*None*,
        **cols**=*None*,
        **res**=*None*,
        **res3**=*None*,
        **nsres**=*None*,
        **ewres**=*None*,
        **nsres3**=*None*,
        **ewres3**=*None*,
        **tbres**=*None*,
        **zoom**=*None*,
        **align**=*None*,
        **grow**=*None*,
        **save**=*None*,
        **format**=*"plain"*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    gs.parse_command("g.region", region="name", format="json")
    ```

## Parameters

=== "Command line"

    **region**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set current region from named region  
    **raster**=*name* [,*name*,...]  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match raster map(s)  
    **raster_3d**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match 3D raster map(s) (both 2D and 3D values)  
    **vector**=*name* [,*name*,...]  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match vector map(s)  
    **n**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the northern edge  
    **s**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the southern edge  
    **e**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the eastern edge  
    **w**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the western edge  
    **t**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the top edge  
    **b**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the bottom edge  
    **rows**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of rows in the new region  
    **cols**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of columns in the new region  
    **res**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;2D grid resolution (north-south and east-west)  
    **res3**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;3D grid resolution (north-south, east-west and top-bottom)  
    **nsres**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 2D grid resolution  
    **ewres**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 2D grid resolution  
    **nsres3**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 3D grid resolution  
    **ewres3**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 3D grid resolution  
    **tbres**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Top-bottom 3D grid resolution  
    **zoom**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Shrink region until it meets non-NULL data from this raster map  
    **align**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Adjust region cells to cleanly align with this raster map  
    **grow**=*value*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of cells to add to each side of the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;A negative number shrinks the current region extent  
    **save**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Save current region settings in named region file  
    **format**=*name* **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    **-d**  
    &nbsp;&nbsp;&nbsp;&nbsp;Set from default region  
    **-s**  
    &nbsp;&nbsp;&nbsp;&nbsp;Save as default region  
    &nbsp;&nbsp;&nbsp;&nbsp;Only possible from the PERMANENT mapset  
    **-p**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region  
    **-l**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region in lat/long using the current ellipsoid/datum  
    **-e**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region extent  
    **-c**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region map center coordinates  
    **-t**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region in GMT style  
    **-w**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the current region in WMS style  
    **-m**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print region resolution in meters (geodesic)  
    **-n**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the convergence angle (degrees CCW)  
    &nbsp;&nbsp;&nbsp;&nbsp;The difference between the projection's grid north and true north, measured at the center coordinates of the current region.  
    **-3**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print also 3D settings  
    **-b**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print the maximum bounding box in lat/long on WGS84  
    **-g**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print in shell script style [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    **-f**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print in one line (flat) in shell script style (ignores format parameter)  
    **-a**  
    &nbsp;&nbsp;&nbsp;&nbsp;Align region to resolution (default = align to bounds, works only for 2D resolution)  
    **-u**  
    &nbsp;&nbsp;&nbsp;&nbsp;Do not update the current region  
    **-o**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force update of the current region  
    **--overwrite**  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    **--help**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print usage summary  
    **--verbose**  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    **--quiet**  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    **--qq**  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    **--ui**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force launching GUI dialog

=== "Python (grass.tools)"

    **region** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set current region from named region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, region, *name*  
    **raster** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match raster map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **raster_3d** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match 3D raster map(s) (both 2D and 3D values)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster_3d, *name*  
    **vector** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match vector map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, vector, *name*  
    **n** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the northern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **s** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the southern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **e** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the eastern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **w** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the western edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **t** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the top edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **b** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the bottom edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **rows** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of rows in the new region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **cols** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of columns in the new region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **res** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;2D grid resolution (north-south and east-west)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **res3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;3D grid resolution (north-south, east-west and top-bottom)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **nsres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 2D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **ewres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 2D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **nsres3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **ewres3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **tbres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Top-bottom 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **zoom** : str | np.ndarray, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Shrink region until it meets non-NULL data from this raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **align** : str | np.ndarray, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Adjust region cells to cleanly align with this raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **grow** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of cells to add to each side of the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;A negative number shrinks the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **save** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Save current region settings in named region file  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, region, *name*  
    **format** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *d*, *s*, *p*, *l*, *e*, *c*, *t*, *w*, *m*, *n*, *3*, *b*, *g*, *f*, *a*, *u*, *o*  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set from default region  
    &nbsp;&nbsp;&nbsp;&nbsp;**s**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Save as default region  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Only possible from the PERMANENT mapset  
    &nbsp;&nbsp;&nbsp;&nbsp;**p**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**l**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in lat/long using the current ellipsoid/datum  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;**c**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region map center coordinates  
    &nbsp;&nbsp;&nbsp;&nbsp;**t**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in GMT style  
    &nbsp;&nbsp;&nbsp;&nbsp;**w**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in WMS style  
    &nbsp;&nbsp;&nbsp;&nbsp;**m**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print region resolution in meters (geodesic)  
    &nbsp;&nbsp;&nbsp;&nbsp;**n**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the convergence angle (degrees CCW)  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The difference between the projection's grid north and true north, measured at the center coordinates of the current region.  
    &nbsp;&nbsp;&nbsp;&nbsp;**3**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print also 3D settings  
    &nbsp;&nbsp;&nbsp;&nbsp;**b**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the maximum bounding box in lat/long on WGS84  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print in shell script style [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    &nbsp;&nbsp;&nbsp;&nbsp;**f**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print in one line (flat) in shell script style (ignores format parameter)  
    &nbsp;&nbsp;&nbsp;&nbsp;**a**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Align region to resolution (default = align to bounds, works only for 2D resolution)  
    &nbsp;&nbsp;&nbsp;&nbsp;**u**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not update the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**o**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Force update of the current region  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  

    Returns:

    **result** : grass.tools.support.ToolResult | None  
    If the tool produces text as standard output, a *ToolResult* object will be returned. Otherwise, `None` will be returned.

    Raises:

    *grass.tools.ToolError*: When the tool ended with an error.

=== "Python (grass.script)"

    **region** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set current region from named region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, region, *name*  
    **raster** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match raster map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **raster_3d** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match 3D raster map(s) (both 2D and 3D values)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster_3d, *name*  
    **vector** : str | list[str], *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Set region to match vector map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, vector, *name*  
    **n** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the northern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **s** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the southern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **e** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the eastern edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **w** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the western edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **t** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the top edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **b** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Value for the bottom edge  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **rows** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of rows in the new region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **cols** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of columns in the new region  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **res** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;2D grid resolution (north-south and east-west)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **res3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;3D grid resolution (north-south, east-west and top-bottom)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **nsres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 2D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **ewres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 2D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **nsres3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;North-south 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **ewres3** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;East-west 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **tbres** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Top-bottom 3D grid resolution  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **zoom** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Shrink region until it meets non-NULL data from this raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **align** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Adjust region cells to cleanly align with this raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **grow** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of cells to add to each side of the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;A negative number shrinks the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *value*  
    **save** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Save current region settings in named region file  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, region, *name*  
    **format** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, shell, json*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**shell**: shell script style output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *d*, *s*, *p*, *l*, *e*, *c*, *t*, *w*, *m*, *n*, *3*, *b*, *g*, *f*, *a*, *u*, *o*  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set from default region  
    &nbsp;&nbsp;&nbsp;&nbsp;**s**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Save as default region  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Only possible from the PERMANENT mapset  
    &nbsp;&nbsp;&nbsp;&nbsp;**p**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**l**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in lat/long using the current ellipsoid/datum  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region extent  
    &nbsp;&nbsp;&nbsp;&nbsp;**c**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region map center coordinates  
    &nbsp;&nbsp;&nbsp;&nbsp;**t**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in GMT style  
    &nbsp;&nbsp;&nbsp;&nbsp;**w**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the current region in WMS style  
    &nbsp;&nbsp;&nbsp;&nbsp;**m**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print region resolution in meters (geodesic)  
    &nbsp;&nbsp;&nbsp;&nbsp;**n**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the convergence angle (degrees CCW)  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The difference between the projection's grid north and true north, measured at the center coordinates of the current region.  
    &nbsp;&nbsp;&nbsp;&nbsp;**3**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print also 3D settings  
    &nbsp;&nbsp;&nbsp;&nbsp;**b**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print the maximum bounding box in lat/long on WGS84  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print in shell script style [deprecated]  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This flag is deprecated and will be removed in a future release. Use format=shell instead.  
    &nbsp;&nbsp;&nbsp;&nbsp;**f**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print in one line (flat) in shell script style (ignores format parameter)  
    &nbsp;&nbsp;&nbsp;&nbsp;**a**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Align region to resolution (default = align to bounds, works only for 2D resolution)  
    &nbsp;&nbsp;&nbsp;&nbsp;**u**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not update the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**o**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Force update of the current region  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*

## DESCRIPTION

The *g.region* module allows the user to manage the settings of the
current geographic region. These regional boundaries can be set by the
user directly and/or set from a region definition file (stored under the
`windows` directory in the user's current mapset). The user can create,
modify, and store as many geographic region definitions as desired for
any given mapset. However, only one of these geographic region
definitions will be current at any given moment, for a specified mapset;
i.e., GRASS programs that respect the geographic region settings will
use the current geographic region settings.

## DEFINITIONS

### Region

In GRASS, a *region* refers to a geographic area with some defined
boundaries, based on a specific map coordinate system and map
projection. Each region also has associated with it the specific
east-west and north-south resolutions of its smallest units (rectangular
units called "cells").

The region's boundaries are given as the northernmost, southernmost,
easternmost, westernmost, bottommost, and topmost points that define
its extent (cell edges). The north and south boundaries are commonly
called *northings*, while the east and west boundaries are called *eastings*.

The region's cell resolution defines the size of the smallest piece of
data recognized (imported, analyzed, displayed, stored, etc.) by GRASS
modules affected by the current region settings. The north-south and
east-west cell resolutions need not be the same, thus allowing
non-square data cells to exist.

Typically all raster and display modules are affected by the current
region settings, but not vector modules. Some special modules diverge
from this rule, for example raster import modules and *v.in.region*.

### Default Region

Each GRASS project (previously called location) has a fixed geographic
region, called the default geographic region (stored in the region file
`DEFAULT_WIND` under the special mapset `PERMANENT`), that defines the
extent of the data base. While this provides a starting point for
defining new geographic regions, user-defined geographic regions need
not fall within this geographic region. The current region can be reset
to the default region with the **-d** flag. The default region is
initially set when the project is first created and can be reset using
the **-s** flag.

### Current Region

Each mapset has a current geographic region. This region defines the
geographic area in which all GRASS displays and raster analyses will be
done. Raster data will be resampled, if necessary, to meet the cell
resolutions of the current geographic region setting.

### Saved Region

Each GRASS MAPSET may contain any number of pre-defined, and named,
geographic regions. These region definitions are stored in the user's
current mapset location under the `windows` directory (also referred to
as the user's saved region definitions). Any of these pre-defined
geographic regions may be selected, by name, to become the current
geographic region. Users may also access saved region definitions stored
under other mapsets in the current project, if these mapsets are
included in the user's mapset search path or the '@' operator is used
(`region_name@mapset`).

### 3D region

The region extent is common between 2D and 3D maps.
However, the 3D resolution, used for 3D raster maps, is set separately
from the 2D resolution that is used for 2D raster maps.
Updating the 2D resolution of the region will not affect its 3D resolution,
and vice versa.

Therefore, people working with 3D raster maps should take care to adjust the
3D resolution of the region using the **res3**, **nsres3**, **ewres3**,
or **tbres** parameters.

## NOTES

After all updates have been applied, the current region's southern and
western boundaries are (silently) adjusted so that the north/south
distance is a multiple of the north/south resolution and that the
east/west distance is a multiple of the east/west resolution.

With the **-a** flag all four boundaries are adjusted to be even
multiples of the resolution, aligning the region to the resolution
supplied by the user. The default is to align the region resolution to
match the region boundaries.

The **-m** flag will report the region resolution in meters. The
resolution is calculated by averaging the resolution at the region
boundaries. This resolution is calculated by dividing the geodesic
distance in meters at the boundary by the number of rows or columns. For
example the east / west resolution (ewres) is determined from an average
of the geodesic distances at the North and South boundaries divided by
the number of columns.

The **-p** (or **-g**) option is recognized last. This means that all
changes are applied to the region settings before printing occurs.

The ****format=shell** parameter prints the current region settings in shell
script style. This format can be given back to *g.region* on its command line.
This may also be used to save region settings as shell environment
variables with the UNIX eval command, "`` eval `g.region -p format=shell` ``".

The **-g** flag is deprecated and will be removed in a future release. Please
use **format=shell** instead.

With **-u** flag current region is not updated even if one or more
options for changing region is used (**res=**, **raster=**, etc). This
can be used for example to print modified region values for further use
without actually modifying the current region. Similarly, **-o** flag
forces to update current region file even when e.g., only printing was
specified. Flag **-o** was added in GRASS version 8 to simulate
*g.region* behavior in prior versions when current region file was
always updated unless **-u** was specified.

### Additional parameter information

Option **zoom** shrinks current region settings to the smallest region
encompassing all non-NULL data in the named raster map layer that fall
inside the user's current region. In this way you can tightly zoom in on
isolated clumps within a bigger map.

If the user also includes the **raster** option on the command
line, **zoom** will set the current region settings to the
smallest region encompassing all non-NULL data in the named **zoom** map
that fall inside the region stated in the cell header for the named
**raster** map.

Option **align** sets the current resolution equal to that of the provided
raster map, and align the current region to a row and column edge in the
named map. Alignment only moves the existing region edges outward to the edges
of the next nearest cell in the named raster map - not to the named map's
edges. To perform the latter function, use the **raster**=*name* option.

## EXAMPLES

### Printing extent and raster resolution in 2D and 3D

This will print the current region in the format:

```sh
g.region -p
```

```sh
projection: 1 (UTM)
zone:       13
datum:      nad27
ellipsoid:  clark66
north:      4928000
south:      4914000
west:       590000
east:       609000
nsres:      20
ewres:      20
rows:       700
cols:       950
```

This will print the current region and the 3D region (used for voxels)
in the format:

```sh
g.region -p3
```

```sh
projection: 1 (UTM)
zone:       13
datum:      nad27
ellipsoid:  clark66
north:      4928000
south:      4914000
west:       590000
east:       609000
top:        1.00000000
bottom:     0.00000000
nsres:      20
nsres3:     20
ewres:      20
ewres3:     20
tbres:      1
rows:       700
rows3:      700
cols:       950
cols3:      950
depths:     1
```

The **format=shell** option prints the region in the following script style
(key=value) format:

```sh
g.region -p format=shell
```

```sh
n=4928000
s=4914000
w=590000
e=609000
nsres=20
ewres=20
rows=700
cols=950
```

The **-b** flag with **format=shell** option prints the region in the following
script style (key=value) format plus the boundary box in latitude-
longitude/WGS84:

```sh
g.region -b format=shell
```

```sh
n=4928000
s=4914000
w=590000
e=609000
nsres=20
ewres=20
rows=700
cols=950
LL_W=-103.87080682
LL_E=-103.62942884
LL_N=44.50164277
LL_S=44.37302019
```

The **-l** option prints the region in the following format:

```sh
g.region -l
```

```sh
long: -103.86789484 lat: 44.50165890 (north/west corner)
long: -103.62895703 lat: 44.49904013 (north/east corner)
long: -103.63190061 lat: 44.37303558 (south/east corner)
long: -103.87032572 lat: 44.37564292 (south/west corner)
rows:       700
cols:       950
Center longitude: 103:44:59.170374W [-103.74977]
Center latitude:  44:26:14.439781N [44.43734]
```

This will print the current region in the format (latitude-longitude
project):

```sh
g.region -pm
```

```sh
projection: 3 (Latitude-Longitude)
zone:       0
ellipsoid:  wgs84
north:      90N
south:      40N
west:       20W
east:       20E
nsres:      928.73944902
ewres:      352.74269109
rows:       6000
cols:       4800
```

Note that the resolution is here reported in meters, not decimal
degrees.

### Changing extent and raster resolution using values

`g.region n=7360100 e=699000`  
This will reset the northing and easting for the current region, but leave
the south edge, west edge, and the region cell resolutions unchanged.

`g.region n=51:36:05N e=10:10:05E s=51:29:55N w=9:59:55E res=0:00:01`  
This will reset the northing, easting, southing, westing and resolution for
the current region, here in DMS latitude-longitude style (decimal
degrees and degrees with decimal minutes can also be used).

`g.region -dp s=698000`  
This will set the current region from the default region for the GRASS
project, reset the south edge to 698000, and then print the result.

`g.region n=n+1000 w=w-500`  
The n=*value* may also be specified as a function of its current value:
n=n+*value* increases the current northing, while n=n-*value* decreases
it. This is also true for s=*value*, e=*value*, and w=*value*. In this
example the current region's northern boundary is extended by 1000 units
and the current region's western boundary is decreased by 500 units.

`g.region n=s+1000 e=w+1000`  
This form allows the user to set the region boundary values relative to
one another. Here, the northern boundary coordinate is set equal to 1000
units larger than the southern boundary's coordinate value, and the
eastern boundary's coordinate value is set equal to 1000 units larger
than the western boundary's coordinate value. The corresponding forms
`s=n-value` and
`w=e-value` may be used to set the values of the region's southern and
western boundaries, relative to the northern and eastern boundary
values.

### Changing extent and raster resolution using maps

`g.region raster=soils`  
This form will make the current region settings exactly the same as
those given in the cell header file for the raster map layer *soils*.

`g.region raster=soils zoom=soils`  
This form will first look up the cell header file for the raster map
layer *soils*, use this as the current region setting, and then shrink
the region down to the smallest region which still encompasses all
non-NULL data in the map layer *soils*. Note that if the parameter
*raster=soils* were not specified, the zoom would shrink to encompass
all non-NULL data values in the soils map that were located within the
*current region* settings.

`g.region -up raster=soils`  
The **-u** option suppresses the re-setting of the current region
definition. This can be useful when it is desired to only extract region
information. In this case, the cell header file for the soils map layer
is printed without changing the current region settings.

`g.region -up zoom=soils save=soils`  
This will zoom into the smallest region which encompasses all non-NULL
soils data values, and save the new region settings in a file to be
called *soils* and stored under the `windows` directory in the user's
current mapset. The current region settings are not changed.

### Changing extent and raster resolution in 3D

`g.region b=0 t=3000 tbres=200 res3=100 g.region -p3`  
This will define the 3D region for voxel computations. In this example a
volume with bottom (0m) to top (3000m) at horizontal resolution (100m)
and vertical resolution (200m) is defined.

### Using g.region in a shell in combination with OGR

Extracting a spatial subset of the external vector map `soils.shp` into
new external vector map `soils_cut.shp` using the OGR *ogr2ogr* tool:  

```sh
eval `g.region -p format=shell`
ogr2ogr -spat $w $s $e $n soils_cut.shp soils.shp
```

This requires that the project and the SHAPE file CRS' match.

### Using g.region in a shell in combination with GDAL

Extracting a spatial subset of the external raster map
`p016r035_7t20020524_z17_nn30.tif` into new external raster map
`p016r035_7t20020524_nc_spm_wake_nn30.tif` using the GDAL *gdalwarp*
tool:  

```sh
eval `g.region -p format=shell`
gdalwarp -t_srs "`g.proj -wf`" -te $w $s $e $n \
         p016r035_7t20020524_z17_nn30.tif \
         p016r035_7t20020524_nc_spm_wake_nn30.tif
```

Here the input raster map does not have to match the project's
coordinate reference system since it is reprojected on the fly.

### JSON Output

```sh
g.region -p format=json
```

Possible output:

```sh
{
    "north": 223550,
    "south": 223480,
    "west": 637830,
    "east": 637900,
    "nsres": 10,
    "ewres": 10,
    "rows": 7,
    "cols": 7,
    "cells": 49,
}
```

```sh
g.region -l format=json
```

Possible output:

```sh
{
    "nw_long": -78.688888505507336,
    "nw_lat": 35.743893244701788,
    "ne_long": -78.669097826118957,
    "ne_lat": 35.743841072010554,
    "se_long": -78.669158624787542,
    "se_lat": 35.728968779193615,
    "sw_long": -78.688945667963168,
    "sw_lat": 35.729020942542441,
    "center_long": -78.679022655614958,
    "center_lat": 35.736431420327719,
    "rows": 165,
    "cols": 179
}
```

### Python example

To get the latitude and longitude coordinates of the region center using
Python, use the `format=json` option along with the `-l` flag:

```python
import grass.script as gs

# Run the g.region command with the -l flag and JSON output format
data = gs.parse_command(
    "g.region",
    flags="l",
    format="json",
)

print(f"center longitude: {data['center_long']}")
print(f"center latitude: {data['center_lat']}")
```

```text
center longitude: -78.679022655614958
center latitude: 35.736431420327719
```

To convert region bbox to wgs84 decimal degrees bbox, use the **g.region**
command with the `-bg` flags and JSON output format:

```python
import grass.script as gs

# Get WGS84 bounding box
region = gs.parse_command(
    "g.region",
    flags="b",
    format="json",
)
bbox = [region[k] for k in ("ll_w", "ll_s", "ll_e", "ll_n")]

print(f"Region bbox to wgs84 decimal degrees bbox: {bbox}")
```

## SEE ALSO

*[g.access](g.access.md), [g.mapsets](g.mapsets.md),
[g.proj](g.proj.md)  
Environment variables: [GRASS_REGION and
WIND_OVERRIDE](variables.md#list-of-selected-internal-grass-environment-variables)*

## AUTHOR

Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

## SOURCE CODE

Available at: [g.region source code](https://github.com/OSGeo/grass/tree/main/general/g.region)
([history](https://github.com/OSGeo/grass/commits/main/general/g.region))  
Accessed: Monday May 11 17:53:59 2026
