pip install

pip install#

These are the install instructions for PmagPy. There are two main ways to install:

The recommended way uses two tools — conda (which manages your Python environment) and pip (which installs PmagPy itself). This is the most reliable approach across macOS, Windows, and Linux, especially if you’ll be using PmagPy regularly on your own computer.
A simpler way uses only pip. This works well in cloud-based notebook environments like Google Colab, where the Python environment is already set up for you.

If you’re not sure which to choose, go with the recommended way. Don’t worry if some of the terms below are new — the steps are spelled out and you don’t need a Python background to follow them.

Recommended approach: conda environment + pip install#

This approach has two parts:

Create a clean Python environment using conda, with the larger scientific Python packages (NumPy, matplotlib, cartopy, etc.) installed up front.
Use pip to install pmagpy and pmagpy-cli on top.

Doing it this way avoids many of the install problems that come up when packages with native (non-Python) components — like cartopy and wxPython — are installed by pip alone. Conda handles those packages more reliably.

Step 1: Install conda (if you don’t have it)#

If you don’t already have a conda-based Python distribution on your computer, install one:

miniforge — a small, fast installer (recommended)
Anaconda — a larger distribution with a graphical installer

Either one provides the conda command you’ll use below. You only need to do this once per computer.

Step 2: Create a PmagPy environment#

Open a terminal:

macOS: open Terminal
Linux: open Terminal
Windows: open Anaconda Prompt (search for it in the Start menu)

Then run this command, which creates a new environment called pmagpy_env and installs the packages PmagPy needs:

conda create -n pmagpy_env -c conda-forge python=3.10 \
    numpy scipy matplotlib pandas \
    cartopy shapely \
    wxpython pyqt jupyterlab

This may take a few minutes the first time. The -c conda-forge part tells conda to use the conda-forge community package channel, which has the most reliable versions of these packages.

When it finishes, activate the environment:

conda activate pmagpy_env

Each time you open a new terminal window and want to use PmagPy, you’ll need to run that conda activate pmagpy_env command again. To leave the environment, run conda deactivate.

Step 3: Install PmagPy#

With the pmagpy_env environment active, install PmagPy and its command-line tools from PyPI:

pip install --upgrade pmagpy
pip install --upgrade pmagpy-cli

That’s it — PmagPy is installed.

Simpler alternative: pure pip#

If you don’t want to use conda — for example, you’re working in Google Colab, JupyterHub, or a lightweight Python environment — you can install PmagPy with pip alone:

pip install --upgrade pmagpy[maps]
pip install --upgrade pmagpy-cli

The [maps] part adds support for making maps (cartopy and shapely). This works on most platforms but can occasionally hit problems on Linux, where cartopy needs system libraries that pip can’t always install. If that happens, switch to the recommended conda approach above.

For a quick install in Google Colab where you don’t need maps:

!pip install pmagpy

Test the install#

Make sure your pmagpy_env environment is active (run conda activate pmagpy_env if it isn’t), then type this in your terminal:

python -c "from pmagpy import pmag; print(pmag.angle([350.0,10.0],[320.0,20.0]))"

You should see something like [30.59060998] printed back.

To test the GUIs, with the environment active, run:

pmag_gui.py

The GUI may take 30 seconds or more to start the first time. If the window doesn’t open, see the troubleshooting page.

Platform notes#

The steps above work on macOS, Windows, and Linux. The notes below cover a few platform-specific quirks worth knowing about.

macOS#

If you see this error when trying to launch a GUI:

This program needs access to the screen.
Please run with a Framework build of python...

…use pmag_gui_anaconda (instead of pmag_gui.py) to launch the GUI. This is a long-standing macOS quirk for wxPython programs.

Windows#

During Anaconda installation, choose “Just Me” rather than “All Users”.
Use the Anaconda Prompt (not the regular Command Prompt). Search for it in the Start menu.
The GUI launcher on Windows is called pmag_gui (no .py at the end).

Linux#

The conda approach in step 2 above is strongly recommended on Linux. Installing wxPython through pip on Linux often runs into trouble because it needs several system libraries (graphics toolkit headers, etc.) and a wheel file specific to your Linux distribution. The conda-forge wxpython package handles all of this for you.

Accessing example data files#

PmagPy ships with example data files used in the documentation and in the textbook Essentials of Paleomagnetism. To copy them to your current working directory, navigate to the directory where you want them and run:

move_data_files.py

(If you have a developer install, the data files are already in the cloned repository at PmagPy/data_files and you don’t need this step.)

Keeping PmagPy up to date#

To upgrade to the latest released version:

pip install --upgrade pmagpy
pip install --upgrade pmagpy-cli

To check what version you have installed:

pip show pmagpy

To uninstall:

pip uninstall pmagpy pmagpy-cli