Getting started
This document covers installation of pyGPlates and a tutorial to get you started using pyGPlates.
Installing pyGPlates
This section covers the installation of pyGPlates.
Starting with version 1.0, pyGPlates can now be installed using conda or pip.
Note
We recommend installing pyGPlates using conda
(since it is designed with binary Python extensions, like pyGPlates, in mind).
However we also provide comprehensive support for pip (via our binary wheels).
Alternatively, you can install pyGPlates from source code. However, that requires installing the required dependency libraries and compilation tools.
Note
PYTHONPATH environment variable.ImportError when pygplates gets imported.Note
PYTHONPATH environment variable to point to the manually installed location.pygplates_0.36.0_docs.zip and follow its installation instructions.Install using conda
PyGPlates installed using conda supports:
Platforms:
Windows (x86-64),
macOS (x86-64) and macOS (ARM64),
Linux (x86-64), Linux (ARM64) and Linux (PPC64LE).
Python:
Version 3.9 - 3.13.
NumPy:
Version 2.x and 1.x.
To install the latest stable version of pyGPlates type the following in a terminal or command window (on macOS and Ubuntu this is a Terminal window, and on Windows you’ll need to open an Anaconda prompt from the Start menu):
conda install -c conda-forge pygplates
We recommend installing pyGPlates into a new conda environment.
For example, the following creates and activates a Python 3.13 environment named pygplates_py313 containing pyGPlates and all its dependency libraries:
conda create -n pygplates_py313 -c conda-forge python=3.13 pygplates
conda activate pygplates_py313
Now you can use pyGPlates. For example, to see the pyGPlates version:
python -c "import pygplates; print(pygplates.__version__)"
Install using pip
PyGPlates installed using pip supports (via our binary wheels):
Platforms:
Windows (x86-64),
macOS 10.15+ (x86-64) and macOS 11.0+ (ARM64),
Linux (x86-64) and Linux (ARM64).
Our manylinux wheels are compatible with Linux distros using glibc 2.17 or later.
Eg, Ubuntu 13.10+, Debian 8+, Fedora 19+, CentOS/RHEL 7+.
Python:
Version 3.8 - 3.13.
NumPy:
Version 1.x (for Python 3.8):
Version 2.x and 1.x (for Python 3.9 and later).
This section demonstrates how to install pyGPlates into the global Python installation.
Warning
On macOS and Linux, to install the latest stable version of pyGPlates type the following in a terminal:
python3 -m pip install pygplates
Note
If python3 doesn’t work then try python.
On Windows, to install the latest stable version of pyGPlates type the following in a command window:
py -m pip install pygplates
Note
On the Windows platform, py installs into the default version of Python (if you have multiple Python installations).
However you can install into a specific Python version. For example, to install into Python 3.13 replace py with py -3.13.
Install into a virtual environment
This section demonstrates how to install pyGPlates into a new virtual environment.
In the following example, we create and activate a Python environment named pygplates_venv that will contain pyGPlates (and all its dependency shared libraries).
This will create a sub-directory called pygplates_venv in the current directory.
On macOS and Linux:
python3 -m venv pygplates_venv
source pygplates_venv/bin/activate
Note
If python3 doesn’t work then try python.
On Windows:
py -m venv pygplates_venv
pygplates_venv\Scripts\activate.bat
Note
On the Windows platform, py creates a virtual environment that uses the default version of Python (if you have multiple Python installations).
However you can create an environment with a specific Python version. For example, for Python 3.13 replace py with py -3.13.
Then you can install pyGPlates into the activated environment with:
python -m pip install pygplates
Note
Once a virtual environment has been activated you can use python on all platforms.
In other words, you do not need to use python3 on macOS and Linux, or py on Windows.
Now you can use pyGPlates. For example, to see the pyGPlates version:
python -c "import pygplates; print(pygplates.__version__)"
And other packages can also be installed (such as packages that depend on pyGPlates).
For example, if you want to create an environment containing gplately (that will use the latest pygplates).
On macOS and Linux:
python3 -m venv gplately_venv
source gplately_venv/bin/activate
python -m pip install gplately
On Windows:
py -m venv gplately_venv
gplately_venv\Scripts\activate.bat
python -m pip install gplately
Note
We did not specify pygplates because gplately will automatically install pygplates.
Install from source code
The first step is to obtain the source code for the current pyGPlates release by checking out the
release-pygplates branch of the GPlates GitHub repository.
Or you can check out the pyGPlates development branch pygplates (if you want the latest unofficial updates).
Note
You’ll first need to install git (if you don’t already have it).
In a terminal or command window, type the following to download the GPlates repository and switch to the release-pygplates branch
(replacing <parent-of-source-code-dir> with the directory you want to download the repository into):
cd <parent-of-source-code-dir>
git clone https://github.com/GPlates/GPlates.git
cd GPlates
git switch release-pygplates
Then follow the instructions in DEPS.Linux (on Linux), DEPS.OSX (on macOS) or DEPS.Windows (on Windows) to install
the dependency libraries required by pyGPlates (and to install the compilation tools).
These instructions are in the root directory of the source code.
Once the dependency libraries (and compilation tools) have been installed then you can compile and install pyGPlates.
To compile pyGPlates and install it into Python (along with its dependency shared libraries), type the following
(assuming you are currently in the root directory of the source code - see cd GPlates above):
python -m pip install .
Note
This assumes a virtual environment has already been activated as described in Install into a virtual environment.
Otherwise you might need to replace python with python3 (on macOS and Linux) or py (on Windows).
Now you can use pyGPlates. For example, to see the pyGPlates version:
python -c "import pygplates; print(pygplates.__version__)"
Note
import pygplates generates shared library conflicts, then you will need to use a build script
in the pygplates/wheel/ directory (of the source code) to build a wheel. And then install that wheel instead.pip install pygplates).auditwheel on Linux, delocate on macOS,
and delvewheel on Windows. This generates unique shared library names to avoid potential conflicts with other installed Python packages that have
the same dependencies as pyGPlates (eg, the GDAL dependency). This is in contrast to installing pyGPlates directly from source code (as described above), which does not
generate unique names because the dependency libraries (that you built above) are simply copied into the Python site-packages installation without renaming them.Troubleshooting
This section covers issues you might encounter when installing or running pyGPlates.
libGL ImportError on Linux
If you have installed pyGPlates using pip and you get the following error on a Linux distribution (when pyGPlates is imported)…
ImportError: libGL.so.1: cannot open shared object file: No such file or directory
…then it’s likely you are using a minimal Linux distribution.
Note
This shouldn’t happen when installing pyGPlates using conda.
For example, you might have a Dockerfile that builds on a Ubuntu Docker base image by installing pyGPlates (using pip).
Or you might be installing pyGPlates (using pip) in an environment like WSL (Windows Subsystem for Linux) where graphical libraries are not always pre-installed.
The solution is to install the libGL.so.1 library. For example, in a Ubuntu Dockerfile you could add the following…
RUN apt-get install -y libgl1-mesa-glx libglib2.0-0
Note
PyGPlates uses GPlates (desktop) functionality.
And a by-product of this is that pyGPlates requires libGL (which is part of the OpenGL implementation used to display graphics in GPlates)
even though pyGPlates doesn’t actually use it.
When you install pyGPlates with pip install pygplates it downloads and installs a wheel for your platform and Python version.
However, on Linux platforms, libGL was not copied into the pyGPlates wheel when it was built (like the other dependency libraries were).
This is because the auditwheel tool (used when building the wheel) whitelisted libGL (since it is expected to be available by default on all Linux distributions).
However libGL.so.1 is not always included by default in some minimal Linux distributions (such as Ubuntu Docker base images)
even though it is available in the usual Linux desktop distributions.
Tutorial
This tutorial first provides a fundamental overview of functions and classes. And then covers the steps to set up and run a simple pyGPlates script.
What are functions and classes ?
Functions
Essentially a function accepts arguments, does some work and then optionally returns a value. The function arguments allow data to be passed to and from the function. Input arguments pass data to the function and output arguments pass data from the function back to the caller. The function return value is also another way to pass data back to the caller. A function argument can be both input and output if the function first reads from it (input) and then writes to it (output).
An example pyGPlates function call is reconstructing coastlines to 10Ma:
pygplates.reconstruct('coastlines.gpmlz', 'rotations.rot', 'reconstructed_coastlines_10Ma.shp', 10)
Note
The pygplates. in front of reconstruct() means the reconstruct() function belongs to the pygplates module.
Also this particular function doesn’t need to a return value.
All four parameters are input parameters since they only pass data to the function
(even though 'reconstructed_coastlines_10Ma.shp' specifies the filename to write the output to).
A similar use of the pygplates.reconstruct() function appends the reconstructed coastlines to a
Python list (instead of writing to a file):
reconstructed_coastline_geometries = []
pygplates.reconstruct('coastlines.gpmlz', 'rotations.rot', reconstructed_coastline_geometries, 10)
# Do something with the reconstructed output.
for reconstructed_geometry in reconstructed_coastline_geometries:
...
The parameter reconstructed_coastline_geometries is now an output parameter because it is used
to pass data from the function back to the caller so that the caller can do something with it.
Classes
Primarily a class is a way to group some data together as a single entity.
An object can be created (instantiated) from a class by providing a specific initial state.
For example, a reconstruct model object can be created (instantiated) from the pygplates.ReconstructModel class
by giving it the features to reconstruct and the rotations used to reconstruct them:
reconstruct_coastlines_model = pyglates.ReconstructModel('coastlines.gpmlz', 'rotations.rot')
Note
This looks like a regular pygplates function call (such as pygplates.reconstruct())
but this is just how you create (instantiate) an object from a class with a specific initial state.
Python uses the special method name __init__() for this and you will see these special methods
documented in the classes listed in the reference section.
You can then call functions (methods) on the reconstruct model object such as reconstructing to a specific reconstruction time
(this particular method returns a reconstruct snapshot object):
reconstruct_coastlines_snapshot = reconstruct_coastlines_model.reconstruct_snapshot(10)
The reconstruct_coastlines_model. before the reconstruct_snapshot(10) means the reconstruct_snapshot() function (method)
applies to the reconstruct_coastlines_model object.
And reconstruct_snapshot() will be one of several functions (methods)
documented in the pygplates.ReconstructModel class.
These class methods behave similarly to top-level functions (such as pygplates.reconstruct()) except
they operate on an instance of class. Hence a class method has an implicit first function
argument that is the object itself (for example, reconstruct_coastlines_model is the implicit argument in
reconstruct_coastlines_snapshot = reconstruct_coastlines_model.reconstruct_snapshot(10)).
Since the returned reconstruct snapshot is another object, you can in turn
call one of its methods. For example:
reconstruct_coastlines_snapshot.export_reconstructed_geometries('reconstructed_coastlines_10Ma.shp')
…to save the reconstructed snapshot (at 10 Ma) to the Shapefile reconstructed_coastlines_10Ma.shp.
A similar use of the reconstruct snapshot class returns the
reconstructed coastlines as a Python list (instead of writing to a file):
reconstructed_coastline_geometries = reconstruct_coastlines_snapshot.get_reconstructed_geometries()
# Do something with the reconstructed output.
for reconstructed_geometry in reconstructed_coastline_geometries:
...
Note
The above example (using classes) demonstrates the alternative to using the pygplates.reconstruct() function.
Note
A complete list of pyGPlates functions and classes can be found in the reference section.
Introductory pyGPlates script
Note
Before starting this section please make sure you have installed pyGPlates.
Source code
Our introductory pyGPlates Python script will contain the following lines of source code:
import pygplates
reconstruct_coastlines_model = pyglates.ReconstructModel('coastlines.gpmlz', 'rotations.rot')
reconstruct_coastlines_snapshot = reconstruct_coastlines_model.reconstruct_snapshot(10)
reconstruct_coastlines_snapshot.export_reconstructed_geometries('reconstructed_coastlines_10Ma.shp')
The first statement…
import pygplates
Note
There are other ways to import pyGPlates but this is the simplest and most common way.
The remaining statements…
reconstruct_coastlines_model = pyglates.ReconstructModel('coastlines.gpmlz', 'rotations.rot')
reconstruct_coastlines_snapshot = reconstruct_coastlines_model.reconstruct_snapshot(10)
reconstruct_coastlines_snapshot.export_reconstructed_geometries('reconstructed_coastlines_10Ma.shp')
…will reconstruct coastlines (loaded from the coastlines.gpmlz file) to their location
10 million years ago (Ma) using the plate rotations in the rotations.rot file, and then save those
reconstructed locations to the Shapefile reconstructed_coastlines_10Ma.shp.
Setting up the script
.py filename extension.tutorial.py (eg, using a text editor).Note
You may want to create a sub-directory in your home directory (such as pygplates_tutorial) to place
the Python script and data files in.
Global_EarthByte_GPlates_PresentDay_Coastlines.gpmlz
and the rotations file is called Zahirovic_etal_2022_OptimisedMantleRef_and_NNRMantleRef.rot.pygplates_tutorial directory and rename them as coastlines.gpmlz and rotations.rot.
Alternatively the filenames (and paths) could be changed in the tutorials.py script to match the geodata.Next open up a terminal or command window (on macOS and Ubuntu this is a Terminal window, and on Windows this is a Command window).
tutorial.py file.cd ~/pygplates_tutorial
Running the script
Next run the Python script by typing:
python tutorial.py
Output of the script
reconstructed_coastlines_10Ma.shp file containing the reconstructed coastline
locations at ten million years ago (10Ma).