Installing SpacePy

The simplest way from zero (no Python) to a working SpacePy setup is:

  1. Install the Anaconda Python environment. 64-bit is recommended.

  2. pip install --upgrade spacepy

If you already have a working Python setup, install SpacePy by:

  1. pip install --upgrade spacepy

In most cases this will install a binary build of SpacePy which includes runtime dependencies. Otherwise it will attempt to compile from source.

If you are familiar with installing Python packages, have particular preferences for managing an installation, or if the above doesn’t work, refer to platform-specific instructions and the details below.

Depending on your Python environment, you may need to explicitly specify Python 3 throughout these commands, e.g. pip3 instead of pip.

The first time a user imports SpacePy, it automatically creates the configuration directory.

If you need further assistance, you can check our support discussions and start a new discussion if there are no discussions on your topic of interest.

SpacePy installs with the common Python distutils and pip.

The latest stable release is provided via PyPI To install from PyPI, make sure you have pip installed:

pip install --upgrade spacepy

If you are installing for a single user, and are not working in a virtual environment, add the --user flag when installing with pip.

Source releases are available from PyPI and our github. Development versions are on github. In addition to downloading tarballs, the development version can be directly installed with:

pip install git+https://github.com/spacepy/spacepy

For source releases, after downloading and unpacking, run (a virtual environment, such as a conda environment, is recommended):

pip install .

or, to install for all users (not in a virtual environment):

sudo pip install .

or, to install for a single user (not in a virtual environment):

pip install . --user

If you do not have administrative privileges, or you will be developing for SpacePy, we strongly recommend using virtual environments.

To install in custom location, e.g.:

pip install . --prefix /n/packages/lib/python

(See --prefix documentation and the related --target, --root).

The closest analogy to the old setup.py handling (no dependency handling, no isolated build) is:

pip install . --no-build-isolation --no-deps

This is recommended if dependencies are managed by the OS or manually.

If installing into the system Python version on Linux (and potentially some other cases), you will need to pass the flag --break-system-packages. Despite the frightening name this is usually safe, although in this case it is recommended to use --no-build-isolation --no-deps and manage the dependencies using the system package manager or conda.

Documentation

If you want to build the documentation yourself (rather than using the online documentation), install sphinx and numpydoc. The easiest way is via pip:

pip install sphinx numpydoc

They are also available via conda:

conda install sphinx numpydoc

Compiling

With the dependencies installed, SpacePy can be built from source. You can always get the latest source code for SpacePy from our github repository and the latest release from PyPI

Following the instructions above will compile before the installation, if installing from source or a binary installer is not available. If this fails, specify the name of, or full path to, the Fortran compiler with the FC environment variable, e.g.:

FC=/usr/local/bin/gfortran pip install .
FC=arm64-apple-darwin20.0.0-gfortran pip install .

The supported compiler is the current GNU gfortran compiler, also called gnu95.

If defined, the LDFLAGS environment variable is also honored when linking irbem. The contents must be valid gfortran flags.

If irbem compilation fails, SpacePy will install without irbempy support. This can be forced by e.g. setting FC to /usr/bin/false.

Troubleshooting

pip failures

If pip completely fails to build, a common issue is a failure in the isolated build environment that pip sets up. Usually this can be addressed by eschewing the separate build environment:

pip install spacepy --no-build-isolation

Another option is manually installing all dependencies (via pip, conda, or other means) and then installing from an unpacked source release with:

pip install --no-build-isolation --no-deps .

pip suppresses detailed output from the build process. To troubleshoot a failure to install, it is useful to write this detailed output to a file using the --log option, e.g.:

pip install spacepy --log=install_log.txt

Please include this log file if opening an issue related to installation.

pip will also cache packages; unfortunately sometimes it will use a cached package which is incompatible with the current environment. In that case, try clearing the cache first, so all locally-compiled packages are rebuilt:

pip cache purge

irbempy

The most common failures relate to compilation of the IRBEM library. Unfortunately pip will hide these warnings, so they manifest when running import spacepy.irbempy (or some other component of SpacePy that uses irbempy).

The error RuntimeError: cannot load IRBEM library; irbempy is not available. means the IRBEM library did not compile at all. This is most likely a compiler issue: either there is no Fortran compiler, or, when using conda on Mac, the correct SDK version has not been installed.