Skip to content

g.mapset

Changes or reports current mapset.

Optionally, creates new mapset or lists available mapsets in given project (location).

g.mapset [-clp] mapset=name [project=name] [dbase=path] format=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

g.mapset mapset=name format=plain

grass.script.parse_command("g.mapset", mapset, project=None, dbase=None, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("g.mapset", mapset="name", format="json")

grass.tools.Tools.g_mapset(mapset, project=None, dbase=None, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.g_mapset(mapset="name", format="json")

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

Parameters

mapset=name [required]
    Name of mapset (default: current search path)
    Name of mapset where to switch
project=name
    Project (location) name
    Project name (not path to project)
dbase=path
    GRASS database directory
    Default: path to the current GRASS database
format=name [required]
    Output format
    Allowed values: plain, json
    Default: plain
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
-c
    Create mapset if it doesn't exist
-l
    List available mapsets and exit
-p
    Print current mapset and exit
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

mapset : str, required
    Name of mapset (default: current search path)
    Name of mapset where to switch
    Used as: output, mapset, name
project : str, optional
    Project (location) name
    Project name (not path to project)
    Used as: input, location, name
dbase : str, optional
    GRASS database directory
    Default: path to the current GRASS database
    Used as: input, dbase, path
format : str, required
    Output format
    Used as: name
    Allowed values: plain, json
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: c, l, p
    c
        Create mapset if it doesn't exist
    l
        List available mapsets and exit
    p
        Print current mapset and exit
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

mapset : str, required
    Name of mapset (default: current search path)
    Name of mapset where to switch
    Used as: output, mapset, name
project : str, optional
    Project (location) name
    Project name (not path to project)
    Used as: input, location, name
dbase : str, optional
    GRASS database directory
    Default: path to the current GRASS database
    Used as: input, dbase, path
format : str, required
    Output format
    Used as: name
    Allowed values: plain, json
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: c, l, p
    c
        Create mapset if it doesn't exist
    l
        List available mapsets and exit
    p
        Print current mapset and exit
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    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.

DESCRIPTION

g.mapset changes the current working mapset, project (formerly known as location), or GISDBASE (directory with one or more projects).

With g.mapset, the shell history (i.e. .bash_history file of the initial project will be used to record the command history.

The g.mapset tool can also report the current mapset and all mapsets in the current project.

NOTES

By default, the shell continues to use the history for the old mapset. To change this behaviour the history can be switched to record in the new mapset's history file as follows:

# bash example
history -w
history -r /"$GISDBASE/$LOCATION/$MAPSET"/.bash_history
HISTFILE=/"$GISDBASE/$LOCATION/$MAPSET"/.bash_history

For parsing the outputs, always use the JSON output. The current plain format may change in a future major release. Please, open an issue if you need a stable parsable format which is not JSON.

EXAMPLES

To print the name of the current mapset, use the -p command as shown below:

# In plain format:
g.mapset -p

# In JSON format:
g.mapset -p format=json

To print the name of the current mapset in JSON format using python:

import grass.script as gs

# Run the g.mapset command with -p flag to print the current mapset using JSON
# output format
data = gs.parse_command(
    "g.mapset",
    flags="p",
    format="json",
)

print(f"project: {data['project']}")
print(f"mapset: {data['mapset']}")

List available mapsets

To list available mapsets, use the -l command as shown below:

# In plain format:
g.mapset -l

# In JSON format:
g.mapset -l format=json

This should list all the mapsets, such as: "landsat new PERMANENT user1."

To print the list of available mapsets in JSON format using python:

import grass.script as gs

# Run the g.mapset command with -l flag to list available mapsets using JSON
# output format
data = gs.parse_command(
    "g.mapset",
    flags="l",
    format="json",
)

print(f"project: {data['project']}")
print(f"mapsets: {' '.join(data['mapsets'])}")

Change the current mapset

To change the current mapset to "user1" use the following command:

g.mapset mapset=user1 project=nc_spm_08_grass7

You should receive the following message: "Mapset switched. Your shell continues to use the history for the old mapset."

Create a new mapset

To create a new mapset, use the -c tag as shown below:

g.mapset -c mapset=new project=nc_spm_08_grass7

SEE ALSO

g.gisenv, g.mapsets

AUTHOR

Radim Blazek

SOURCE CODE

Available at: g.mapset source code (history)
Latest change: Thursday Jun 26 06:08:13 2025 in commit 191f39f