Install & Compatibility
Where this runs
tested against v1.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 8.18s
184MB installed
● package 184MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
healpy
✓ import healpy as hp
Standard alias for convenience.
mollview
✓ hp.mollview(map_data)
✗ healpy.mollview() without alias
Most visualization functions are commonly accessed via the `hp` alias. Ensure `matplotlib.pyplot` is also imported for displaying plots.
This quickstart demonstrates how to create a basic HEALPix map using a NumPy array and visualize it with `healpy.mollview()`. It sets up a map at a given `NSIDE` resolution, populates it with pixel indices, and then displays it with coordinate graticules.
import numpy as np
import healpy as hp
import matplotlib.pyplot as plt
# Define the resolution parameter NSIDE (must be a power of 2)
NSIDE = 32
# Calculate the number of pixels
NPIX = hp.nside2npix(NSIDE)
print(f"Number of pixels for NSIDE={NSIDE}: {NPIX}")
# Create a simple map (e.g., an array with pixel indices)
m = np.arange(NPIX, dtype=float)
# Visualize the map using Mollweide projection
hp.mollview(m, title="Simple Healpix Map (RING ordering)")
hp.graticule() # Add meridians and parallels
plt.show()
Debug
Known issues
breakingThe `blm_gauss()` function in version 1.19.0 was updated to use the `l(l+1)` formula, aligning with `gauss_beam()` and standard definitions. Previously, it used the `l^2` formula. This changes the computed spherical harmonic coefficients for Gaussian beams.fixIf relying on precise `blm_gauss()` values, re-evaluate results or adjust calculations based on the new formula. Consider if older versions should be used for backward compatibility with previous computations.
affects: >=1.19.0
gotchaHealpy officially supports Linux and macOS. While Windows is supported through the Windows Subsystem for Linux (WSL), native Windows builds are not supported and may lead to installation or runtime issues.fixFor Windows users, use WSL for a supported environment. Alternatively, consider using `conda` for pre-compiled binaries which often simplify installation on various platforms.
affects: All versions
gotchaWhen installing from source, especially if external HEALPix C++ or `cfitsio` libraries are detected, compilation might fail if OpenMP is used by the external library but not supported by your C/C++ compiler (e.g., clang). Conflicts with `cfitsio` from HEASOFT due to a `rotmatrix.h` header clash are also known.fixIf OpenMP compilation fails, try `python setup.py clean --all` and set `CC` and `CXX` environment variables to an OpenMP-capable compiler (e.g., `gcc`/`g++`). For `cfitsio` conflicts, ensure you are not using the HEASOFT provided `cfitsio` or compile `healpy` with its bundled `cfitsio` (default behavior if `pkg-config` doesn't find external ones).
affects: All versions (source builds)
deprecatedStarting from `healpy` 1.15.0, the `logging` module is used for messages instead of `warnings`. All `verbose` keywords in functions are deprecated and will be removed in future versions.fixConfigure logging via `import logging; log = logging.getLogger('healpy'); log.setLevel(logging.DEBUG)` for detailed messages. Remove `verbose=True` or similar keyword arguments from function calls. affects: >=1.15.0
gotchaHealpy maps typically use the `hp.UNSEEN` constant (`-1.6375e+30`) to mark invalid or unseen pixels. While most `healpy` functions handle this automatically, directly working with `numpy.ma.MaskedArray` via `hp.ma` requires flipping the mask convention (NumPy's `True` means masked, `healpy`'s mask derived from `UNSEEN` might be `0` for masked).fixBe mindful of mask conventions when converting between `healpy`'s internal representation and `numpy.ma.MaskedArray`. If `hp.ma` is used, explicitly flip the mask if necessary: `masked_array.mask = ~unseen_mask` or similar, depending on how `unseen_mask` is generated.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'healpy'
The `healpy` package is not installed in the current Python environment, or the environment where it is installed is not active.
fixEnsure `healpy` is installed using `pip install healpy` or `conda install -c conda-forge healpy`, and activate the correct Python environment before running your script.
failed with error code 1 in /private/var/folders/.../pip-install-.../healpy/
This error typically indicates that the `healpy` package failed to compile from source during installation, often due to missing build dependencies (like C/C++ compilers or development libraries) or specific platform issues (e.g., on macOS or Windows without WSL).
fixFor Anaconda/Miniconda users, use `conda install -c conda-forge healpy`. For pip users on systems where binaries are not available (e.g., some macOS versions or Linux without necessary dev tools), ensure required build tools like `libssl-dev` (Debian/Ubuntu) or `openssl-dev` (CentOS) and a C++ compiler are installed. On macOS, consider using MacPorts if pip/conda fail.
TypeError: bad number of pixels
This error occurs when a `healpy` function, such as `healpy.write_map` or other map manipulation functions, receives an array with a number of pixels that does not correspond to a valid HEALPix `nside` parameter.
fixEnsure the input array's length (number of pixels) is a valid HEALPix pixel count (e.g., `12 * nside**2`) for the `nside` you are working with. You can verify validity using `healpy.pixelfunc.isnpixok()` or get `nside` from `npix` using `healpy.pixelfunc.npix2nside()`.
ValueError: Unknown format code 'd' for object of type 'str'.
This `ValueError` often arises when `healpy.read_map` attempts to read a FITS file where the header information, specifically related to `NSIDE`, is not in the expected integer format, or there are other inconsistencies in how the file's data types are interpreted by the underlying FITS reading library (Astropy).
fixInspect the FITS file header (e.g., using `astropy.io.fits.open('filename.fits')[0].header`) to understand the format of the 'NSIDE' keyword or other relevant data. If the file is a non-standard HEALPix FITS file, you might need to read it using `astropy.io.fits` directly and then manually construct a `healpy` map, or specify the `dtype` parameter in `hp.read_map` if the data type is causing issues. RuntimeError: Unknown exception
This error, particularly when using functions like `healpy.query_polygon`, can occur if the input polygon is self-intersecting or topologically irregular, which the underlying HEALPix C++ library cannot handle.
fixEnsure that the `vertices` array passed to `healpy.query_polygon` defines a simple, non-self-intersecting polygon. You may need to pre-process your polygon vertices to remove self-intersections or simplify complex shapes before passing them to `healpy` functions.
Upgrade
Version history
1.19.0latest on PyPI · released Dec 2, 2025
Audit
Dependencies
numpyrequiredCore numerical operations and map representation (tested with >=1.19).
matplotliboptionalRequired for visualization functions (optional since 1.17.0).
scipyoptionalRequired for some advanced functions (optional since 1.17.0).