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	6.4.0	6.4.0
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.13. In the root folder you will find a symbolic link environment.yml, which points to the file docs/environment_files/gcpy_environment_py313.yml file. Ths file contains the package specifications listed above under the Version (Python 3.13) column.

We also maintain a GCPy environment file for backwards compatibility with Python 3.12 (docs/environment_files/gcpy_environment_py312.yml). However, we have not yet been able to construct a GCPy environment using Python 3.14, due to conflicts in installing the esmf and xesmf packages. We hope to be able to resolve this in the near future.

Methods for installing GCPy

You can choose among the following installation methods:

GCPy installation methods

Method	Complexity	Who should use it
Install GCPy from conda-forge (Recommended)	Simple	Most GCPy users
Install GCPy from PyPI	Simple	Those who do not wish to install a Conda environment
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 conda-forge

GCPy is available through the conda-forge channel under the name geoschem-gcpy. 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 Conda on your system, please see our Install the Conda Python package manager Supplemental Guide.

1. Create and activate a Python virtual environment

You will use Conda to create a Python virtual environment named gcpy_env, into which you will install GCPy and its dependencies. A Python virtual environment is a named set of Python 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.

To create and activate the GCPy Python environment, use these commands:

$ conda create -n gcpy_env
$ conda activate gcpy_env
(gcpy_env) $

Activating the environment adds the (gcpy_env) prefix added to the command prompt. This is a visual cue to remind you that the environment is active.

2. Install GCPy with Conda

Next, install GCPy from conda-forge:

(gcpy_env) $ conda install geoschem-gcpy

Conda will ask you to confirm that you want to proceed with the installation. Type y to proceed.

3. Verify the installation

Run the Create a Test Plot example script to validate the installation. If you see a plot created on your screen, GCPy has been installed successfully.

4. Deactivate the Python environment

Next, deactivate the gcpy_env environment:

(gcpy_env) $ conda deactivate
$

This also removes the (gcpy_env) prefix from the command prompt.

You may now skip ahead to the next chapter.

Install GCPy from PyPI

If you do not wish to create a Python virtual environment, you may 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.

Attention

If you install GCPy from PyPI, you will lose the ability to keep the Python packages needed for GCPy separate from other Python packages. This can potentially lead to package conflicts. For this reason we recommend installing GCPy from conda-forge.

1. Install GCPy with Pip

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

$ pip install geoschem-gcpy

2. Validate the installation

Run the Create a Test Plot example script to validate the installation. If you see a plot created on your screen, GCPy has been installed successfully.

(Optional) Update to a newer GCPy version

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 next chapter.

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 Python virtual environment with Conda. If Conda is not already installed on your system, you may follow the instructions in our Install the Conda Python package manager Supplemental Guide.

Install GCPy and its dependencies

Once you have made sure that a 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 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.

GCPy ships with YAML files that specify Python environments for Python 3.12 and 3.13. These are located in the docs/environment_files folder. The symbolic link environment.yml, located in the top-level directory of the package, points to the default environment (which is based on Python 3.13).

Use this command to create a Python environment named gcpy_env for use with GCPy:

$ conda env create -n gcpy_env --file=environment.yml

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:

$ conda activate gcpy_env
(gcpy_env) $

Activating the GCPy Python environment adds the (gcpy_env) added to the command prompt. This is a visual cue to remind you that the environment is active.

To exit the environment, use this command:

(gcpy_env) $ conda deactivate
$

Deactivating the environment removes (gcpy_env) from the command prompt.

3. Add GCPy to PYTHONPATH

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

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   # or MacOSX if you are on a Mac

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                                 # Or, close and reopen your terminal

$ echo $PYTHONPATH                                     # Check it contains path to your GCPy clone

$ conda activate gcpy_env                              # Activate the environment

(gcpy_env) $ conda list                                # Check it contains contents of gcpy env file

You may now run the Create a Test Plot example script. If you see a plot created on your screen, the installation was successful.

Then deactivate the environment with:

(gcpy_env) conda deactivate
$

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:

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