Developer install

Developer install#

A developer install lets you work directly from the PmagPy source code on your computer: edits to the code take effect immediately, you can switch between branches, and you can stay current with the latest changes between releases. Use this install path if you want to contribute to PmagPy or follow development closely.

If you only want to use PmagPy as a library and don’t need the latest unreleased changes, the pip install page covers the simpler workflow.

Recommended approach#

The same three-step pattern works on macOS, Windows, and Linux:

Create a conda environment with the scientific Python packages and GUI libraries.
Clone the PmagPy repository.
Install pmagpy as an editable package with pip install -e . so your imports point at the cloned repo.

Step 1: Create a conda environment#

If you don’t already have a conda-based Python distribution, install miniforge (recommended) or Anaconda.

Create a fresh environment with the dependencies that benefit most from conda-forge:

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

Step 2: Clone PmagPy#

If you don’t have git, install it first. Then change to the directory where you want the PmagPy folder, and clone:

git clone https://github.com/PmagPy/PmagPy.git
cd PmagPy

You now have a full local copy of the PmagPy source.

Step 3: Install in editable mode#

From the PmagPy directory:

pip install -e ".[maps]"

The -e flag installs PmagPy as an editable package — Python imports from your cloned repo directly, so any code changes (or git pull) take effect immediately without reinstalling. The [maps] part adds cartopy and shapely; you can drop it if you already installed those via conda above and would like pip to leave them alone. The quotes keep zsh (the macOS default shell) from treating the square brackets as a glob pattern.

Running the command-line programs#

There are three patterns for using the command-line programs (pmag_gui.py, magic_gui.py, demag_gui.py, thellier_gui.py, the conversion scripts, etc.) after a developer install. Pick the one that fits your workflow.

Pattern A: Navigate and run (simplest)#

If you mostly edit library code and only occasionally launch the GUIs, just cd into the programs/ directory and run them:

cd /path/to/PmagPy/programs
python pmag_gui.py

No second install, no PATH changes. This is a fine default for most contributors.

Pattern B: Editable install of pmagpy-cli (not currently available)#

The command-line programs are packaged separately as pmagpy-cli from command_line_setup.py, and pip install -e . only reads setup.py. The older python command_line_setup.py develop route is deprecated by setuptools and, with current versions (setuptools 80 and later), no longer installs the program entry points, so there is at present no working editable install of the CLI. Use Pattern A to run the programs from the repository, or Pattern C to pair the editable library with the released CLI.

Pattern C: Editable library + released CLI#

If you only edit library code (not the GUIs), you can have an editable install of the library and the released CLI side by side:

pip install -e ".[maps]"
pip install pmagpy-cli

This is the cleanest separation when you’re not touching programs/ or dialogs/.

Test the install#

Make sure your pmagpy_dev environment is active (run conda activate pmagpy_dev if it isn’t). Then test core library functionality:

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

You should see something like [30.59060998].

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

pmag_gui.py

(On macOS, if pmag_gui.py raises a This program needs access to the screen error, try pmag_gui_anaconda instead. If you used Pattern A above, cd into PmagPy/programs first.)

Keeping a developer install up to date#

From the PmagPy directory:

git pull

Because the install is editable, the next import pmagpy will use the updated code — no reinstall needed. The exception is when setup.py itself changes (for example, new dependencies are added), in which case rerun:

pip install -e ".[maps]"

Working with branches#

To test a feature branch, work on a contribution, or reproduce a bug against master:

git checkout <branch-name>

Your editable install will now import from that branch’s code. Switching branches needs no reinstall.

Platform notes#

macOS#

Both bash and zsh work as the shell. zsh has been default since macOS Catalina.
The wxPython-based GUI launchers may need to be invoked as pmag_gui_anaconda rather than pmag_gui.py if you see a “needs access to the screen” / Framework build error.

Windows#

During Anaconda installation, choose “Just Me” rather than “All Users”.
Use the Anaconda Prompt rather than the regular Command Prompt if conda activate doesn’t work.
The GUI launcher on Windows is pmag_gui (no .py suffix).

Linux#

The conda-forge wxpython package (already covered in step 1 above) is by far the most reliable way to get a working GUI stack on Linux. Pip-installed wxPython on Linux historically requires a long list of system libraries (libgtk-3-dev, libgstreamer1.0-0, etc.) and a wheel file specific to your Linux distribution.
If you see ImportError: libwx_gtk3u_core-3.0.so.0: cannot open shared object file after a non-conda wxPython install, switch to the conda-forge package.

Note on dev_setup.py#

Older PmagPy documentation referenced a dev_setup.py script that put the cloned repository on PYTHONPATH and its programs/ directories on PATH by editing ~/.bashrc, ~/.bash_profile and ~/.profile. The script was removed from the repository in September 2026 in favor of the editable install above. If you ran it in the past, you can delete the block it added to those files (the lines mentioning PMAGPATHS and PmagPy/programs); an editable install does not need them.