The fastest way to install PyGMT is with the mamba or conda package manager which takes care of setting up a virtual environment, as well as the installation of GMT and all the dependencies PyGMT depends on:
mamba create --name pygmt --channel conda-forge pygmt
conda create --name pygmt --channel conda-forge pygmt
To activate the virtual environment, you can do:
mamba activate pygmt
conda activate pygmt
After this, check that everything works by running the following in a Python interpreter (e.g., in a Jupyter notebook):
import pygmt pygmt.show_versions()
You are now ready to make you first figure! Start by looking at the tutorials on our sidebar, good luck!
The sections below provide more detailed, step by step instructions to install and test PyGMT for those who may have a slightly different setup or want to install the latest development version.
PyGMT is tested to run on Python 3.8 or greater.
We recommend using the Mambaforge Python distribution to ensure you have all dependencies installed and the mamba package manager in the base environment. Installing Mambaforge does not require administrative rights to your computer and doesn’t interfere with any other Python installations on your system.
PyGMT requires Generic Mapping Tools (GMT) version 6 as a minimum, which is the latest released version that can be found at the GMT official site. We need the latest GMT (>=6.3.0) since there are many changes being made to GMT itself in response to the development of PyGMT, mainly the new modern execution mode.
Compiled conda packages of GMT for Linux, macOS and Windows are provided through conda-forge. Advanced users can also build GMT from source instead.
We recommend following the instructions further on to install GMT 6.
PyGMT requires the following libraries to be installed:
The following are optional dependencies:
IPython: For embedding the figures in Jupyter notebooks (recommended).
Contextily: For retrieving tile maps from the internet.
GeoPandas: For using and plotting GeoDataFrame objects.
Installing GMT and other dependencies
Before installing PyGMT, we must install GMT itself along with the other
dependencies. The easiest way to do this is via the
conda package manager.
We recommend working in an isolated
to avoid issues with conflicting versions of dependencies.
First, we must configure conda to get packages from the conda-forge channel:
conda config --prepend channels conda-forge
Now we can create a new virtual environment with Python and all our dependencies
installed (we’ll call it
pygmt but feel free to change it to whatever you
mamba create --name pygmt python=3.11 numpy pandas xarray netcdf4 packaging gmt
conda create --name pygmt python=3.11 numpy pandas xarray netcdf4 packaging gmt
Activate the environment by running the following (do not forget this step!):
mamba activate pygmt
conda activate pygmt
From now on, all commands will take place inside the virtual environment called
pygmt and won’t affect your default
Now that you have GMT installed and your virtual environment activated, you can install PyGMT using any of the following methods:
Using mamba/conda (recommended)
This installs the latest stable release of PyGMT from conda-forge:
mamba install pygmt
conda install pygmt
This upgrades the installed PyGMT version to be the latest stable release:
mamba update pygmt
conda update pygmt
This installs the latest stable release from PyPI:
pip install pygmt
You can also run
pip install pygmt[all] to install pygmt with
all of its optional dependencies.
Alternatively, you can install the latest development version from TestPyPI:
pip install --pre --extra-index-url https://test.pypi.org/simple/ pygmt
To upgrade the installed stable release or development version to be the latest
one, just add
--upgrade to the corresponding command above.
Any of the above methods (mamba/conda/pip) should allow you to use the PyGMT package from Python.
Testing your install
To ensure that PyGMT and its dependencies are installed correctly, run the following in your Python interpreter:
import pygmt pygmt.show_versions() fig = pygmt.Figure() fig.coast(region="g", frame=True, shorelines=1) fig.show()
If you see a global map with shorelines, then you’re all set.
Notes for Jupyter users
If you can successfully import pygmt in a Python interpreter or IPython, but
ModuleNotFoundError when importing pygmt in Jupyter, you may need to
pygmt virtual environment (using
mamba activate pygmt or
conda activate pygmt) and install a
pygmt kernel following the commands below:
python -m ipykernel install --user --name pygmt # install virtual environment properly jupyter kernelspec list --json
After that, you need to restart Jupyter, open your notebook, select the
pygmt kernel and then import pygmt.