Installing¶
Note
🚨 This package is in early stages of design and implementation. 🚨
We welcome any feedback and ideas! Let us know by submitting issues on Github or send us a message on our Gitter chatroom.
Which Python?¶
You’ll need Python 3.6 or greater to run PyGMT.
We recommend using the Anaconda Python
distribution to ensure you have all dependencies installed and the conda
package manager available.
Installing Anaconda does not require administrative rights to your computer and
doesn’t interfere with any other Python installations in your system.
Which GMT?¶
PyGMT requires GMT 6 as a minimum, which you can find the latest development version at this GitHub repository.
We need the very latest GMT since there are many changes being made to GMT itself in response to the development of PyGMT, mainly the new modern execution mode.
GMT 6 has not been officially released yet, but will be soon! In the meantime, GMT does provide compiled conda packages of their development version for Linux, Mac and Windows through conda-forge. Advanced users can also build GMT from source instead, which is not so recommended but we would love to get feedback from anyone who tries.
We recommend following the instructions further on to install GMT 6.
Dependencies¶
PyGMT requires the following libraries:
The following are optional (but recommended) dependencies:
- IPython: For embedding the figures in Jupyter notebooks.
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 using the conda package manager.
We recommend working in an isolated
conda environment
to avoid issues with competing versions of its dependencies.
First, we must configure conda to get packages from the conda-forge channel (the order is important):
conda config --prepend channels conda-forge/label/dev
conda config --prepend channels conda-forge
Now we can create a new conda environment with Python and all our dependencies installed
(we’ll call it pygmt but you can change it to whatever you want):
conda create --name pygmt python=3.6 pip numpy pandas xarray packaging gmt=6.0.0rc*
Activate the environment by running:
conda activate pygmt
From now on, all commands will take place inside the conda virtual environment and won’t affect your default installation.
Note
Currently, this has only been tested to work on Linux and macOS. We don’t have tests running on Windows yet, so things might be broken. Please report any errors by creating an issue on Github.
Installing PyGMT¶
Now that you have GMT installed and your conda environment activated,
use pip to install the latest source of PyGMT from Github:
pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip
Alternatively, you can clone the git repository and install using pip:
git clone https://github.com/GenericMappingTools/pygmt.git
cd pygmt
pip install .
This will allow you to use the pygmt library from Python.
Testing your install¶
PyGMT ships with a full test suite. You can run our tests after you install it but you will need a few extra dependencies as well (be sure to have your conda env activated):
conda install pytest pytest-mpl sphinx jinja2 docutils ipython
Test your installation by running the following inside a Python interpreter:
import pygmt
pygmt.test()