Registry / data / astropy-healpix

astropy-healpix

library1.1.3pypypi✓ verified 85d ago

astropy-healpix provides HEALPix (Hierarchical Equal Area isolations of the Sphere) functionality, including coordinate transformations, pixelization, and query methods, tightly integrated with the Astropy ecosystem. It is currently at version 1.1.3 and maintains an active development status, with releases often coordinated with major Astropy versions or for bug fixes as needed.

data

pip install astropy-healpix

github ↗package ↗

INSTALL

IMPORT

SIG · ASTROPY-HEALPIX

astropy-healpix

datapythonv1.1.3

Install

6.5s avg

Import

1875ms

Disk

157MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.3 · 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

musl

glibc

py 3.10

✓ —

✓ 6.35s

py 3.11

✓ —

✓ 6.08s

py 3.12

✓ —

✓ 6.15s

py 3.13

✓ —

✓ 6.38s

py 3.9

✕ build_error

✓ 7.55s

157MB installed

● package 157MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HEALPix

✓ from astropy_healpix import HEALPix

✗ from astropy.healpix import HEALPix

HEALPix is part of the dedicated `astropy-healpix` library, not directly `astropy.healpix` (which might refer to an internal Astropy module or a coordinate frame).

HpxGeom

✓ from astropy_healpix import HpxGeom

This quickstart demonstrates how to initialize a `HEALPix` object, convert HEALPix pixel indices to sky coordinates, and convert sky coordinates back to pixel indices. It uses common Astropy coordinate and unit objects for integration.

from astropy_healpix import HEALPix from astropy.coordinates import ICRS, SkyCoord from astropy import units as u import numpy as np # Create a HEALPix object with nside=32, 'nested' order, and ICRS frame hp = HEALPix(nside=32, order='nested', frame=ICRS()) # Convert HEALPix pixel indices to SkyCoord objects pixel_indices = np.array([0, 100, 20000]) sky_coords = hp.healpix_to_skycoord(pixel_indices) print(f"Sky Coordinates for pixels {pixel_indices}:\n{sky_coords}") # Convert SkyCoord objects to HEALPix pixel indices ra = np.array([0, 10, 20]) * u.deg dec = np.array([0, 5, 10]) * u.deg coords_to_convert = SkyCoord(ra, dec, frame='icrs') pix_at_coords = hp.skycoord_to_healpix(coords_to_convert) print(f"HEALPix pixels for coordinates {coords_to_convert}: {pix_at_coords}")

Debug

Known issues

breakingThe default value of the `order` parameter for `HEALPix` and `HpxGeom` constructors changed from `'ring'` to `'nested'` in `astropy-healpix v1.0.0`. If your code relies on the implicit `'ring'` order from older versions and you update, it will now silently produce incorrect pixel indices or coordinate conversions unless `order='ring'` is explicitly set.

fix

Explicitly specify `order='ring'` in your `HEALPix` or `HpxGeom` constructor if you intend to use ring ordering (e.g., `HEALPix(nside=32, order='ring', frame=ICRS())`).

affects: >=1.0.0

gotcha`astropy-healpix` has specific minimum `astropy` requirements (e.g., `>=5.0.0` for `astropy-healpix` 1.x.x). Using an older `astropy` version can lead to `ImportError`s, `TypeError`s, or unexpected behavior due to API mismatches between the two libraries.

fix

Always ensure your `astropy` installation meets the minimum version requirement specified by `astropy-healpix` (typically found in the `pyproject.toml` or `setup.cfg` on GitHub, or PyPI's `Requires-Dist` section).

affects: <1.0.0

gotchaThe `nside` parameter, which determines the resolution of the HEALPix grid, must always be a power of 2 (e.g., 1, 2, 4, 8, 16, 32, ...). Providing a non-power-of-2 integer will result in a `ValueError`.

fix

Ensure the value passed to `nside` is always a power of 2. For example, `HEALPix(nside=64, ...)` is valid, but `HEALPix(nside=10, ...)` is not.

affects: all

Errors

Common errors & fixes

ImportError: cannot import name 'HEALPix' from 'astropy.healpix'

Users often confuse the dedicated `astropy-healpix` library with an internal or deprecated `astropy.healpix` module, leading to incorrect import paths.

fix

The correct import path for the `astropy-healpix` library is `from astropy_healpix import HEALPix` (note the underscore).

ValueError: nside must be a power of 2

The `nside` parameter for `HEALPix` or `HpxGeom` was set to an integer that is not a power of 2.

fix

Change `nside` to a power of 2 (e.g., 2, 4, 8, 16, 32, 64, etc.). For instance, `HEALPix(nside=32, ...)` is valid, while `HEALPix(nside=50, ...)` is not.

TypeError: HpxGeom() got an unexpected keyword argument 'frame'

The `frame` argument was incorrectly passed to the `HpxGeom` class. `HpxGeom` represents the geometric properties of a HEALPix grid and does not require a coordinate frame; `frame` is only applicable to the `HEALPix` class which handles sky coordinates.

fix

Remove the `frame` argument when initializing `HpxGeom`. If you need to work with sky coordinates, use the `HEALPix` class instead.

Upgrade

Version history

1.1.3latest on PyPI · released Jan 19, 2026

Audit

Dependencies

astropyrequiredCore dependency for coordinate systems, units, and general astronomical utilities.

numpyrequiredFundamental library for numerical operations on arrays.

scipyrequiredUsed for certain spatial and mathematical operations.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/astropy/astropy-healpix ↗

packagehttps://pypi.org/project/astropy-healpix/ ↗