Installing GCPy

In this chapter we will walk you through the steps of installing GCPy on your computer system

Requirements

Platforms

GCPy is currently supported on the following platforms:

1. Linux (x86_64)

2. Windows Subsystem for Linux under Microsoft Windows 11

3. MacOS

Software dependencies

GCPy requires several other Python packages, which are listed below.

GCPy dependencies

Package	Version (Python 3.12)	Version (Python 3.13)
cartopy	0.23.0	0.24.0
cf_xarray	0.9.1	0.10.0
dask	2025.3.0	2025.3.0
esmf [1]	8.6.1	8.8.1
esmpy [1]	8.6.1	8.8.1
gridspec	0.1.0	0.1.0
ipython	8.25.0	9.0.0
joblib	1.4.2	1.4.2
jupyter	1.0.0	1.1.1
matplotlib	3.8.4	3.10.1
netcdf4	1.6.5	1.7.2
netcdf-fortran	4.6.1	4.6.1
numpy	1.26.4	2.1.3
pandas	2.2.2	2.2.3
pip	24.0	25.0.1
pylint	3.2.2	3.3.4
pyproj	3.6.1	3.7.1
python	3.12.0	3.13.0
pypdf	4.2.0	5.3.1
requests	2.32.3	2.32.3
scipy	1.13.1	1.15.2
sparselt	0.1.3	0.1.3
tabulate	0.9.0	0.9.0
tk	8.6.13	8.6.13
xarray	2024.5.0	2025.1.2
xesmf	0.8.5	0.8.5

Notes

[1] (1,2)

GCPy requires the esmf and esmpy packages, which are not supported on Microsoft Windows. Thus, the only way to use GCPy on a Windows PC is from within a Windows Subsystem for Linux (WSL) instance.

The default GCPy environment uses Python 3.12. In the root folder you will find a symbolic link environment.yml, which points to the file docs/environment_files/gcpy_environment_py312.yml file. Ths file contains the package specifications listed above under the Version (Python 3.12) column.

We also maintain GCPy environment files for newer Python versions (e.g. docs/environment_files/gcpy_environment_py313.yml, which is based on Python 3.13). This will allow you to build a GCPy environment based on a newer Python version, which is often necessary for testing and development. For most GCPy users, it should be sufficient to use the default environment based on Python 3.12.

Methods for installing GCPy

You can choose among the following installation methods:

GCPy installation methods

Method	Complexity	Who should use it
Install GCPy from PyPI	Simple	Most GCPy users
Install GCPy from conda-forge	Medium	GCPy users who have experience building mamba/conda environments
Download GCPy with Git and build a Python virtual environment	Complex	GCPy developers

Unless you are going to be actively developing GCPy, you should install from conda-forge.

Install GCPy from PyPI

If you only plan on using GCPy for visualization of GEOS-Chem simulation results, you can install GCPy from the Python Package Index (PyPi) using the Pip installer.

If your system does not already have Pip installed, you may install it with the get-pip.py script.

First-time installation with Pip

Once you are sure that Pip is installed, you may proceed to download GCPy with this command:

$ pip install geoschem-gcpy

To validate the installation, we recommend running the Create a Test Plot example script.

Updating to a newer version with Pip

Use this command to update an existing GCPy installation to a newer version:

$ pip install -U geoschem-gcpy

You may now skip ahead to the Specify backend for Matplotlib chapter.

Install GCPy from conda-forge

GCPy is available through the conda-forge channel under the name geoschem-gcpy. Mamba or Conda will handle the installation of all dependencies and sub-dependencies for GCPy, which includes many Python packages and several non-Python libraries. If you do not already have a version of Mamba or Conda on your system, please see our Install Mamba or Conda Python package manager Supplemental Guide.

Installing GCPy with Mamba

Use these Mamba commands to create a Python environment named gcpy_env and to install GCPy into this environment.

$ mamba create -n gcpy_env
$ mamba activate gcpy_env
$ mamba install geoschem-gcpy

After you have installed GCPy, check if the installation was successful by running a test program:

$ export MPLBACKEND=tkagg   # Sets the matplotlib backend to Tk/Tcl
$ python -m gcpy.examples.plotting.create_test_plot

If a plot appears on your screen, you have installed GCPy successfully. Close the plot window (click the close button or type q) and then deactivate the environment:

$ mamba deactivate

Installing GCPy with Conda

Use these Mamba commands to create a Python environment named gcpy_env and to install GCPy into this environment.

$ conda create -n gcpy_env
$ conda activate gcpy_env
$ conda install geoschem-gcpy

After you have installed GCPy, check if the installation was successful by running a test program:

$ export MPLBACKEND=tkagg   # Sets the matplotlib backend to Tk/Tcl
$ python -m gcpy.examples.plotting.create_test_plot

If a plot appears on your screen, you have installed GCPy successfully. Close the plot window (click the close button or type q) and then deactivate the environment:

$ conda deactivate

Download GCPy with Git and build a Python virtual environment

If you plan on actively developing GCPy, we recommend that you install GCPy from Git and create a Mamba or Conda environment. If you do not already have a version of Mamba or Conda on your system, please see our Install Mamba or Conda Python package manager Supplemental Guide.

Install GCPy and its dependencies

Once you have made sure that a Mamba or Conda installation exists on your system, you may create a Python environment for GCPy. Follow these steps:

1. Download the GCPy source code.

   Create and go to the directory in which you would like to store GCPy. In this example we will store GCPy in your $HOME/python/ path, but you can store it wherever you wish. You can also name the GCPy download whatever you want. In this example the GCPy directory is called GCPy.

   $ cd $HOME/python
   $ git clone https://github.com/geoschem/gcpy.git GCPy
   $ cd GCPy
   

   
   

2. Create a new Python virtual environment for GCPy.

   A Python virtual environment is a named set of Python installs, e.g. packages, that are independent of other virtual environments. Using an environment dedicated to GCPy is useful to maintain a set of package dependencies compatible with GCPy without interfering with Python packages you use for other work. You can create a Python virtual environment from anywhere on your system. It will be stored in your Mamba (or Conda installation rather than the directory from which you create it).

   You can create a Python virtual environment using a file that lists all packages and their versions to be included in the environment. GCPy includes such as file, environment.yml, located in the top-level directory of the package.

   Run one of the following commands at the command prompt to create a virtual environment for use with GCPy. You can name environment whatever you wish. This example names it gcpy_env.

   $ mamba env create -n gcpy_env --file=environment.yml   # If using Mamba
   
   $ conda env create -n gcpy_env --file=environment.yml   # If using Conda
   

   A list of packages to be downloaded will be displayed. A confirmation message will ask you if you really wish to install all of the listed packages. Type Y to proceed or n to abort.

   Once successfully created you can activate the environment with one of these commands:

   $ mamba activate gcpy_env   # If using Mamba
   
   $ conda activate gcpy_env   # If using Conda
   

   To exit the environment, use one of these commands:

   $ mamba deactivate   # If using Mamba
   
   $ conda deactivate   # If using Conda
   

   
   

3. Add GCPy to PYTHONPATH

   The environment variable PYTHONPATH specifies the locations of Python libraries on your system that were not installed by Mamba.

   Add the path to your GCPy source code folder ~/.bashrc file:

   export PYTHONPATH=$PYTHONPATH:$HOME/python/GCPy
   

   and then use

   $ source ~/.bashrc
   

   to apply the change.
   
   

4. Set the MPLBACKEND environment variable

   The environment variable MPLBACKEND specifies the X11 backend that the Matplotlib package will use to render plots to the screen.

   Add this line to your ~/.bashrc file on your local PC/Mac and on any remote computer systems where you will use GCPy:

   export MPLBACKEND=tkagg
   

   And then use:

   $ source ~/.bashrc
   

   to apply the change.
   
   

5. Perform a simple test:

   Make sure that you have specified the proper Specify backend for Matplotlib for your system. Then run the following commands in your terminal:

   $ source $HOME/.bashrc                      # Alternatively close and reopen your terminal
   $ echo $PYTHONPATH                          # Check it contains path to your GCPy clone
   $ mamba activate gcpy_env
   $ mamba list                                # Check it contains contents of gcpy env file
   $ python -m gcpy.examples.create_test_plot  # Create a test plot
   

If the plot appears on your screen, then the GCPy installation was successful.

If no error messages are displayed, you have successfully installed GCPy and its dependencies.

Upgrading GCPy versions

Sometimes the GCPy dependency list changes with a new GCPy version, either through the addition of new packages or a change in the minimum version. You can always update to the latest GCPy version from within you GCPy clone, and then update your virtual environment using the environment.yml file included in the package.

Run the following commands to update both your GCPy version to the latest available.

$ cd $HOME/python/GCPy
$ git fetch -p
$ git checkout main
$ git pull

You can also checkout an older version by doing the following:

$ cd $HOME/python/GCPy
$ git fetch -p
$ git tag
$ git checkout tags/version_you_want

Once you have the version you wish you use you can do the following commands to then update your virtual environment:

$ mamba activate gcpy_env
$ cd $HOME/python/GCPy
$ mamba env update --file environment.yml --prune