Getting started with GRASS for Conda

tutorial

grass

python

Get started with GRASS for Conda.

Author

Brendan Harmon

Published

May 3, 2026

This is a very short introduction to the GRASS Python package distributed via Conda. With the GRASS Python package, you can call GRASS tools in Python scripts or Jupyter notebooks. This means that you can easily integrate GRASS into data science workflows using the Python scientific ecosystem. This brief tutorial covers:

Installing the Conda package and environment manager
Creating a GRASS environment with Conda
Running GRASS in Python

Manager

Conda is an open source package and environment manager. Many open source projects use Conda to publish their software as Python packages. With Conda, you can easily install collections of these packages in isolated environments to avoid conflicting software dependencies. The GRASS Python package is distributed via conda-forge, a community smithy and repository [1]. Install Miniforge, a minimal distribution of Conda that uses conda-forge as its default channel [2].

Unix

On Unix-like platforms - including Linux, MacOS, and Windows Subsystem for Linux -
download the installation shell script and then run it in a terminal:

bash Miniforge3-$(uname)-$(uname -m).sh

Windows

For Windows, download and run the binary installer. See here for more detailed instructions.

Environment

Now that Conda is installed, let’s use it to create an environment for GRASS. We will install the GRASS and Jupyter Lab Python packages and all of their dependencies into this environment. In a terminal, run conda create to create a GRASS environment named grass. Then use conda install to install the GRASS package. Next, run conda activate to start the environment.

conda create --name grass
conda install grass jupyterlab
conda activate grass

You can do this with just one line of code:

conda create -n grass grass jupyterlab && conda activate grass

Notebook

Let’s try the GRASS Python package in a Jupyter notebook. We will using scripting to display maps from a sample dataset. We will download the dataset, start a GRASS session in the dataset, and then display raster and vector maps from the dataset. Let’s begin by launching Jupyter Lab from the terminal. This will open an new Jupyter notebook in a web browser window.

jupyter lab

Start GRASS

To start a GRASS session, we need to define a project and its coordinate reference system. For this demonstration, we will use the Natural Earth Dataset for GRASS [3]. This dataset is a GRASS project with a collection of global raster and vector data in the World Geodetic System 1984. Download and unarchive the dataset. Then start a GRASS session using the dataset as a project. Read more about projects in GRASS here. Since the dataset is approximately 120MB, it may take a couple of minutes to download. As a test that GRASS started correctly, run g.proj with flag g to print the current projection.

# Import libraries
import os
import sys
import subprocess
from pathlib import Path
import requests
from zipfile import ZipFile

# Find GRASS Python packages
sys.path.append(
  subprocess.check_output(
    ["grass", "--config", "python_path"],
    text=True
    ).strip()
  )

# Import GRASS packages
import grass.script as gs
import grass.jupyter as gj

# Set GRASS database
gisdbase = Path.home() / "grassdata"

# Download dataset
url = "https://zenodo.org/records/13370131/files/natural_earth_dataset.zip?download=1"
filepath = gisdbase / "natural_earth_dataset.zip"
request = requests.get(url, allow_redirects=True)
if request.status_code != 200:
    raise ConnectionError(f"Error downloading file: {request.status_code}")
filepath.write_bytes(request.content)

# Unarchive dataset
with ZipFile(filepath, 'r') as archive:
    archive.extractall(gisdbase)

# Delete archive
os.remove(filepath)

# Start GRASS in project
session = gj.init(gisdbase / "natural_earth_dataset")

# Print projection information
gs.run_command("g.proj", flags="g")

Display raster map

The Natural Earth raster is a global basemap with land cover and shaded relief rendered with a natural color scheme. Display the Natural Earth raster map with d.rast.

# Display natural earth raster
m = gj.Map(width=800)
m.d_rast(map="natural_earth")
m.show()

Display vector map

Now display a vector map of global rivers. First apply a thematic color gradient to the rivers based on their stream order with v.colors. Then display the map with d.vect, scaling the line width by stream order.

# Display rivers
m = gj.Map(width=800)
gs.run_command("v.colors", map="rivers", use="attr", column="scalerank", color="water")
m.d_vect(map="rivers", width_column="strokeweig", width_scale=2)
m.show()

References

[1]

conda-forge community. 2015. The conda-forge Project: Community-based software distribution built on the conda package format and ecosystem. https://doi.org/10.5281/zenodo.4774217

[2]

conda-forge community. 2026. Miniforge. Retrieved from https://conda-forge.org/download/

[3]

Brendan Harmon and Paulo van Breugel. 2020. Natural earth dataset for GRASS GIS. https://doi.org/10.5281/zenodo.3762773

Reuse

CC BY-SA 4.0

--- title: "Getting started with GRASS for Conda" author: Brendan Harmon date: last-modified license: CC BY-SA categories: [tutorial, grass, python] description: > Get started with GRASS for Conda. image: images/natural-earth-01.webp bibliography: grass.bib csl: ../acm.csl links: grass_projects: "[projects](https://grass.osgeo.org/grass-devel/manuals/grass_projects.html)" g_proj: "[g.proj](https://grass.osgeo.org/grass-stable/manuals/g.proj.html)" d_rast: "[d.rast](https://grass.osgeo.org/grass-stable/manuals/d.rast.html)" d_vect: "[d.vect](https://grass.osgeo.org/grass-stable/manuals/d.vect.html)" v_colors: "[v.colors](https://grass.osgeo.org/grass-stable/manuals/v.colors.html)" conda_create: "[conda create](https://docs.conda.io/projects/conda/en/stable/commands/create.html)" conda_install: "[conda install](https://docs.conda.io/projects/conda/en/stable/commands/install.html)" conda_activate: "[conda activate](https://docs.conda.io/projects/conda/en/stable/commands/activate.html)" code-links: - text: Python script href: grass-conda.py icon: file-code target: _blank resources: grass-conda.py format: ipynb: default html: toc: true code-tools: true code-copy: true engine: jupyter execute: eval: false jupyter: python3 --- ![Natural Earth](images/natural-earth-01.webp) This is a very short introduction to the [GRASS Python package](https://grass.osgeo.org/download/conda/) distributed via Conda. With the GRASS Python package, you can call GRASS tools in Python scripts or Jupyter notebooks. This means that you can easily integrate GRASS into data science workflows using the Python scientific ecosystem. This brief tutorial covers: * Installing the Conda package and environment manager * Creating a GRASS environment with Conda * Running GRASS in Python  ## Manager Conda is an open source package and environment manager. Many open source projects use Conda to publish their software as Python packages. With Conda, you can easily install collections of these packages in isolated environments to avoid conflicting software dependencies. The GRASS Python package is distributed via conda-forge, a community smithy and repository [@condaforge]. Install [Miniforge](https://conda-forge.org/download/), a minimal distribution of Conda that uses conda-forge as its default channel [@Miniforge]. ::: {.callout-note title="Unix"} On Unix-like platforms - including {{< fa brands linux >}} Linux, {{< fa brands apple >}} MacOS, and {{< fa brands microsoft >}}{{< fa brands linux >}} Windows Subsystem for Linux - download the installation shell script and then run it in a terminal: ```{bash} bash Miniforge3-$(uname)-$(uname -m).sh ``` ::: ::: {.callout-note title="Windows"} For {{< fa brands microsoft >}} Windows, download and run the binary installer. See [here](https://github.com/conda-forge/miniforge#install) for more detailed instructions. ::: ## Environment Now that Conda is installed, let's use it to create an environment for GRASS. We will install the GRASS and Jupyter Lab Python packages and all of their dependencies into this environment. In a terminal, run {{< meta links.conda_create >}} to create a GRASS environment named `grass`. Then use {{< meta links.conda_install >}} to install the GRASS package. Next, run {{< meta links.conda_activate >}} to start the environment. ```{bash} conda create --name grass conda install grass jupyterlab conda activate grass ``` You can do this with just one line of code: ```{bash} conda create -n grass grass jupyterlab && conda activate grass ```  ## Notebook Let's try the GRASS Python package in a Jupyter notebook. We will using scripting to display maps from a sample dataset. We will download the dataset, start a GRASS session in the dataset, and then display raster and vector maps from the dataset. Let's begin by launching Jupyter Lab from the terminal. This will open an new Jupyter notebook in a web browser window. ```{bash} jupyter lab ``` ### Start GRASS To start a GRASS session, we need to define a project and its coordinate reference system. For this demonstration, we will use the Natural Earth Dataset for GRASS [@NaturalEarth]. This dataset is a GRASS project with a collection of global raster and vector data in the World Geodetic System 1984. Download and unarchive the dataset. Then start a GRASS session using the dataset as a project. Read more about {{< meta links.grass_projects >}} in GRASS here. Since the dataset is approximately 120MB, it may take a couple of minutes to download. As a test that GRASS started correctly, run {{< meta links.g_proj >}} with flag `g` to print the current projection. ```{python} # Import libraries import os import sys import subprocess from pathlib import Path import requests from zipfile import ZipFile # Find GRASS Python packages sys.path.append( subprocess.check_output( ["grass", "--config", "python_path"], text=True ).strip() ) # Import GRASS packages import grass.script as gs import grass.jupyter as gj # Set GRASS database gisdbase = Path.home() / "grassdata" # Download dataset url = "https://zenodo.org/records/13370131/files/natural_earth_dataset.zip?download=1" filepath = gisdbase / "natural_earth_dataset.zip" request = requests.get(url, allow_redirects=True) if request.status_code != 200: raise ConnectionError(f"Error downloading file: {request.status_code}") filepath.write_bytes(request.content) # Unarchive dataset with ZipFile(filepath, 'r') as archive: archive.extractall(gisdbase) # Delete archive os.remove(filepath) # Start GRASS in project session = gj.init(gisdbase / "natural_earth_dataset") # Print projection information gs.run_command("g.proj", flags="g") ``` ### Display raster map The Natural Earth raster is a global basemap with land cover and shaded relief rendered with a natural color scheme. Display the Natural Earth raster map with {{< meta links.d_rast >}}. ```{python} # Display natural earth raster m = gj.Map(width=800) m.d_rast(map="natural_earth") m.show() ``` ![Natural Earth](images/natural-earth-01.webp) ### Display vector map Now display a vector map of global rivers. First apply a thematic color gradient to the rivers based on their stream order with {{< meta links.v_colors >}}. Then display the map with {{< meta links.d_vect >}}, scaling the line width by stream order. ```{python} # Display rivers m = gj.Map(width=800) gs.run_command("v.colors", map="rivers", use="attr", column="scalerank", color="water") m.d_vect(map="rivers", width_column="strokeweig", width_scale=2) m.show() ``` ![Rivers](images/natural-earth-02.webp)