Installation procedure for Healpy

(NOTE: if high performance of the installed package is important, e.g. when installing in computing centers or for performing benchmarks, please be sure to read the Generating native binaries section below.)


Healpy depends on the HEALPix C++ and cfitsio C libraries. Source code for both is included with Healpy and is built automatically, so you do not need to install them yourself. Only Linux and macOS are supported, Windows only through the “Windows Subsystem for Linux” (see below).

Installation from package managers

Debian users may install Healpy for the Debian-supplied system Python interpreter by running:

sudo apt-get install python3-healpy

MacPorts users on macOS may install Healpy for the MacPorts-supplied Python interpreter by running:

sudo port install py39-healpy

Compilation issues with Mac OS

Currently most people report they cannot install healpy on Mac OS either via pip or building from source, due to the impossibility of compiling the HEALPix based extension. The best alternatives are conda, binary installation with pip, or MacPorts.

Installation on Mac OS with MacPorts

If you are using a Mac and have the MacPorts package manager, it’s even easer to install Healpy with:

sudo port install py39-healpy

Installation with a package manager on Debian and Ubuntu

Binary apt-get style packages are also available in the development versions of Debian (sid) and Ubuntu.

Almost-as-quick installation from official source release

Healpy is also available in the Python Package Index (PyPI). You can download it with:

curl -O

and build it with:

tar -xzf healpy-*.tar.gz
cd healpy-*
pip install .

If everything goes fine, you can test it:

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> import healpy as hp
>>> hp.mollview(np.arange(12))

or run the test suite with:

cd healpy-* && pytest

Building against external Healpix and cfitsio

Healpy uses pkg-config to detect the presence of the Healpix and cfitsio libraries. pkg-config is available on most systems. If you do not have pkg-config installed, then Healpy will download and use (but not install) a Python clone called pykg-config.

If you want to provide your own external builds of Healpix and cfitsio, then download the following packages:

If you are going to install the packages in a nonstandard location (say, --prefix=/path/to/local), then you should set the environment variable PKG_CONFIG_PATH=/path/to/local/lib/pkgconfig when building. No other environment variable settings are necessary, and you do not need to set PKG_CONFIG_PATH to use Healpy after you have built it.

Then, unpack each of the above packages and build them with the usual configure; make; make install recipe.

Installation on Windows through the “Windows Subsystem for Linux”

  1. Restart your computer, and follow the instructions (which appear before windows starts) to enter BIOS. Usually this means pressing DEL or F2 just after powering on. Find the option to enable virtualization (exact name will depend on your system, can google your machine brand name + “enable virtualization” for instructions)

  2. Follow these instructions to install Windows Subsystem for Linux: Following the instructions for WSL version 2, and choosing Ubuntu from the store.

  3. Restart machine

  4. Open the newly installed Ubuntu application from the Start menu and follow the setup instructions.

  5. When they are complete, run these commands:

    sudo apt-get update
    sudo apt-get upgrade
    sudo apt-get install python3 python3-pip
  6. Quit ubuntu, restart it, and run:

    pip3 install numpy jupyter matplotlib healpy ipython jupyter
  7. Quit ubuntu again, restart it, and run:

    ipython notebook --no-browser
  8. Copy and paste the line starting with http://localhost:8888/?token= into your normal Windows web browser.

Development install

Developers building from a snapshot of the github repository need:

  • autoconf and libtool (in Debian or Ubuntu: sudo apt-get install autoconf automake libtool pkg-config)

  • libssl-dev (Debian) or openssl-dev (CentOS) is required to build cfitsio from source

  • run git submodule init and git submodule update to get the bundled HEALPix sources

The best way to install healpy if you plan to develop is to do a development mode (a.k.a. “editable” install) with pip by adding the -e flag:

pip install -e .

In case of compilation errors, see the note above in the pip section.

Generating native binaries

Using pre-compiled wheels is typically the easiest and quickest way to install healpy on a system. However, the performance of the installed package may not be optimal, since the wheel has to work on all CPUs of a given architecture (e.g. x86_64) and will therefore probably not use all features present in your local CPU. A healpy installation which is custom-tailored for a specific target CPU may be two or three times faster for some operations (most notably alm2map* and map2alm* calls).

To achieve target-specific compilation, healpy must be installed from source and the -march=native flag has to be passed to the compilers. While details may vary slightly depending on the target platform, the installation command will have this basic form:

CC=gcc CXX=g++ CFLAGS="-fPIC -O3 -march=native" CXXFLAGS="-fPIC -O3 -march=native" pip3 install --user --no-binary healpy healpy


When you run “python”, temporary build products are placed in the “build” directory. If you want to clean out and remove the build directory, then run:

python clean --all