Install

Install#

Online usage (Binder)#

See below for the full installation instructions. If instead you’d like to use this package online, without needing to install anything, check out our Binder link, which gives full access to the latest released version of the package in an online environment.

Install Python#

Before installing PolarToolkit, ensure you have Python 3.9 or greater installed. If you don’t, I recommend setting up Python with Miniforge. See the install instructions here.

Install PolarToolkit#

The fastest way to install PolarToolkit is with the mamba or conda package manager which takes care of setting up a virtual environment, as well as the installation of PolarToolkit and all its dependencies:

mamba create --name polartoolkit --channel conda-forge polartoolkit

conda create --name polartoolkit --channel conda-forge polartoolkit

To activate the virtual environment, you can do:

mamba activate polartoolkit

conda activate polartoolkit

Test your install#

After this, check that everything works by running the following in a Python interpreter (e.g., in a Jupyter notebook):

import polartoolkit
polartoolkit.__version__

This should tell you which version was installed.

To further test, you can clone the GitHub repository and run the suite of tests, see the Contributors Guide.

A simpler method to ensure the basics are working would be to download any of the Tutorials or How-to guides and run them locally. On the documentation, each of the examples should have a drop down button in the top right corner to download the .ipynb.

You are now ready to use PolarToolkit! Start by looking at our Quickstart Guide, Tutorials, or How-To Guides. Good luck!

Note

The sections below provide more detailed, step by step instructions to install and test PolarToolkit for those who may have a slightly different setup or want to install the latest development version.

Alternative Install methods#

Pip#

Instead, you can use pip to install polartoolkit, but first you need to install a few dependencies with conda. This is because pygmt, geopandas, and cartopy all rely on C packages, which can only be successfully install with conda/mamba and not with pip.

Create a new virtual environment:

mamba create --name polartoolkit --channel conda-forge pygmt geopandas cartopy

conda create --name polartoolkit --channel conda-forge polartoolkit

To activate the virtual environment, you can do:

mamba activate polartoolkit

conda activate polartoolkit

Install polartoolkit with pip:

pip install polartoolkit

Note

to install the optional dependencies, use this instead: pip install polartoolkit[all]

Development version#

You can use pip, with the above created environment, to install the latest source from GitHub:

pip install git+https://github.com/mdtanker/polartoolkit.git

Or you can clone the repository and install:

git clone https://github.com/mdtanker/polartoolkit.git
cd polartoolkit
pip install .

Common errors#

If you get errors related to GDAL and GMT, try reinstalling Geopandas and PyGMT with the following command:

mamba install geopandas pygmt --force-reinstall -y --channel conda-forge

If you get errors related to the PyProj, try the following:

mamba install -c conda-forge proj-data --force-reinstall -y --channel conda-forge

or

mamba remove --force pyproj -y
pip install pyproj --force-reinstall

If you get an error related to traitlets run the following command as discussed here:

mamba install ipykernel --update-deps --force-reinstall -y

If you are still having errors, then you can download the environment.yml file from here and create a conda environment directly from this:

mamba create --file PATH_TO_FILE

where you replace PATH_TO_FILE with the path to your downloaded environment.yml file.

Contents