h3

library4.5.0pypypi✓ verified 24d ago

h3 is a set of Python bindings for Uber's H3 C library, a hierarchical hexagonal geospatial indexing system. It allows for efficient spatial indexing, querying, and analysis using hexagonal grids. The current version is 4.4.2, and it typically sees multiple releases per year, often in sync with updates to the underlying H3 C library.

serialization data

pip install h3

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · H3

serializationpythonv4.5.0

Install

1.7s avg

Import

128ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.5.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.130s · 20.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.126s · 21MB

19MB installed

● package 19MB

Code

Verified usage

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

✓ import h3

This quickstart demonstrates how to convert geographic coordinates to an H3 index, retrieve its center and boundary, find its neighbors, and validate an H3 index.

import h3 # Example coordinates: San Francisco lat, lon = 37.7749, -122.4194 # 1. Get an H3 index for a given lat/lon at a specific resolution resolution = 9 h3_index = h3.geo_to_h3(lat, lon, resolution) print(f"H3 Index for ({lat}, {lon}) at resolution {resolution}: {h3_index}") # 2. Get the geographic coordinates of the center of an H3 index center_coords = h3.h3_to_geo(h3_index) print(f"Center coordinates of {h3_index}: {center_coords}") # 3. Get the boundary (polygon) of an H3 index boundary = h3.h3_to_geo_boundary(h3_index) print(f"Boundary of {h3_index} (first 2 points): {boundary[:2]}...") # 4. Find immediate neighbors of an H3 index (k-ring with distance 1) neighbors = h3.h3_k_ring(h3_index, 1) print(f"Neighbors of {h3_index}: {list(neighbors)}") # 5. Check if an H3 index is valid is_valid = h3.h3_is_valid(h3_index) print(f"Is {h3_index} valid? {is_valid}")

h3 --version

Debug

Known issues

breakingFuture versions of h3-py (e.g., v4.5.0 stable) will drop support for Python 3.8 and 3.9. The minimum supported Python version will be 3.10.

fix

Ensure your project is running on Python 3.10 or newer before upgrading to h3-py v4.5.0 or later.

affects: >=4.5.0a1

breakingThe functions `cells_to_h3shape` and `cells_to_geo` will become stricter in their input validation. Supplying duplicate cells will now raise an `H3DuplicateInputError`, and supplying cells of mixed resolutions will raise an `H3ResMismatchError`.

fix

Before passing cell sets to `cells_to_h3shape` or `cells_to_geo`, ensure all cells are unique and of the same resolution to avoid runtime errors.

affects: >=4.5.0a2

gotchaPrior to v4.5.0a2, `cells_to_h3shape` and `cells_to_geo` could produce incorrect results or fail silently for polygons that cross the antimeridian or poles, or for very large polygons. While newer versions fix this behavior, they also introduce stricter input validation (see breaking change above).

fix

For critical applications involving global polygons, upgrade to v4.5.0 or newer and ensure your input cell sets are valid according to the new strict validation rules (unique and same resolution).

affects: <4.5.0a2

breakingThe `h3-py` library underwent a significant API change in version 4.0.0. Key functions like `h3.geo_to_h3` were renamed to `h3.h3_geo_to_h3` (and similar for other functions like `h3.h3_to_geo`, `h3.h3_to_geo_boundary`). Code written for `h3-py` v3.x will raise `AttributeError` if run with v4.x or later.

fix

Update your code to use the new function names, e.g., replace `h3.geo_to_h3(...)` with `h3.h3_geo_to_h3(...)`.

affects: >=4.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'h3'

The 'h3' package is not installed in the active Python environment or the Python interpreter cannot find it.

fix

Ensure the package is installed using pip: `pip install h3` or `pip3 install h3`. If using a virtual environment or conda, activate it first.

AttributeError: module 'h3' has no attribute 'latlng_to_cell'

This error typically occurs when using h3-py version 4.x code with an older h3-py version (3.x) or vice-versa, as function names changed significantly between major versions (e.g., `h3.h3_to_geo` became `h3.cell_to_latlng`). The error string shows a v4 function name which is not found in a v3 installation, or a v3 function name not found in a v4 installation.

fix

Upgrade to the latest h3-py version (`pip install --upgrade h3`) and update your code to use the v4 API (e.g., `h3.latlng_to_cell` instead of `h3.geo_to_h3`, `h3.cell_to_boundary` instead of `h3.h3_to_geo_boundary`). Alternatively, if you need v3 behavior, explicitly install a v3 version (`pip install 'h3<4'`) and use its API.

ImportError: cannot import name 'h3' from 'h3' (/path/to/h3/__init__.py)

This specific error often arises when a library (like `h3pandas`) attempts to import `h3.h3`, a common pattern in older `h3-py` (v3.x) that is no longer valid in `h3-py` v4.x, where the `h3` module itself is the top-level API.

fix

This usually indicates a dependency conflict. Either downgrade `h3` to a compatible v3.x version for the dependent library (`pip install 'h3~=3.0'`) or upgrade the dependent library (e.g., `h3pandas`) to a version compatible with `h3-py` v4.x.

ERROR: Could not find a version that satisfies the requirement h3 (from versions: none)

This indicates that `pip` could not find a suitable distribution of the `h3` package for your Python version and operating system. This often happens with packages that rely on C extensions if necessary build tools are missing or if the Python version is not supported by available wheels.

fix

Ensure you are using a supported Python version (h3-py >=3.8). Update `pip` (`pip install --upgrade pip`). If on Windows, ensure you have a C++ compiler (like Visual Studio Build Tools) and CMake installed, as `h3` requires compiling its C core if a pre-built wheel isn't available.

TypeError: Invalid argument, not a string or column: DataFrame[...] of type <class 'pyspark.sql.dataframe.DataFrame'>

This error typically occurs when you are trying to pass an entire DataFrame or a DataFrame column object directly to an `h3` function that expects a single H3 index (as a string or integer) or a simple Python iterable of indices, rather than a Spark/Pandas DataFrame construct.

fix

When working with DataFrames (especially PySpark), use User-Defined Functions (UDFs) to apply `h3` functions row-wise on specific columns. For pandas, apply the function to a Series. Example for pandas: `df['h3_index'].apply(lambda x: h3.h3_to_parent(x, resolution))`.

Upgrade

Version history

4.5.0latest on PyPI · released May 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/uber/h3-py ↗

packagehttps://pypi.org/project/h3/ ↗

homepagehttps://h3geo.org ↗

docshttps://uber.github.io/h3-py/ ↗

changeloghttps://uber.github.io/h3-py/_changelog.html ↗