{"id":1503,"library":"h3","title":"H3 Python Bindings","description":"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.","status":"active","version":"4.4.2","language":"python","source_language":"en","source_url":"https://github.com/uber/h3-py","tags":["geospatial","h3","mapping","hexagonal","spatial-indexing"],"install":[{"cmd":"pip install h3","lang":"bash","label":"Install h3"}],"dependencies":[],"imports":[{"symbol":"h3","correct":"import h3"}],"quickstart":{"code":"import h3\n\n# Example coordinates: San Francisco\nlat, lon = 37.7749, -122.4194\n\n# 1. Get an H3 index for a given lat/lon at a specific resolution\nresolution = 9\nh3_index = h3.geo_to_h3(lat, lon, resolution)\nprint(f\"H3 Index for ({lat}, {lon}) at resolution {resolution}: {h3_index}\")\n\n# 2. Get the geographic coordinates of the center of an H3 index\ncenter_coords = h3.h3_to_geo(h3_index)\nprint(f\"Center coordinates of {h3_index}: {center_coords}\")\n\n# 3. Get the boundary (polygon) of an H3 index\nboundary = h3.h3_to_geo_boundary(h3_index)\nprint(f\"Boundary of {h3_index} (first 2 points): {boundary[:2]}...\")\n\n# 4. Find immediate neighbors of an H3 index (k-ring with distance 1)\nneighbors = h3.h3_k_ring(h3_index, 1)\nprint(f\"Neighbors of {h3_index}: {list(neighbors)}\")\n\n# 5. Check if an H3 index is valid\nis_valid = h3.h3_is_valid(h3_index)\nprint(f\"Is {h3_index} valid? {is_valid}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project is running on Python 3.10 or newer before upgrading to h3-py v4.5.0 or later.","message":"Future 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.","severity":"breaking","affected_versions":">=4.5.0a1"},{"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.","message":"The 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`.","severity":"breaking","affected_versions":">=4.5.0a2"},{"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).","message":"Prior 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).","severity":"gotcha","affected_versions":"<4.5.0a2"},{"fix":"Update your code to use the new function names, e.g., replace `h3.geo_to_h3(...)` with `h3.h3_geo_to_h3(...)`.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'4.4.2':39 'allow':24 'analysi':31 'bind':3,10 'c':15,57 'current':36 'effici':26 'geospati':20,59 'grid':34 'h3':1,4,14,56,60 'hexagon':19,33,62 'hierarch':18 'index':21,28,65 'librari':16,58 'map':61 'multipl':44 'often':48 'per':46 'python':2,9 'queri':29 'releas':45 'see':43 'set':7 'spatial':27,64 'spatial-index':63 'sync':50 'system':22 'typic':42 'uber':12 'under':55 'updat':52 'use':32 'version':37 'year':47","created_at":"2026-04-09T03:50:44.532519+00:00","updated_at":"2026-04-16T15:31:28.926762+00:00","problems":[{"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.","cause":"The 'h3' package is not installed in the active Python environment or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'h3'"},{"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.","cause":"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.","error":"AttributeError: module 'h3' has no attribute 'latlng_to_cell'"},{"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.","cause":"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.","error":"ImportError: cannot import name 'h3' from 'h3' (/path/to/h3/__init__.py)"},{"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.","cause":"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.","error":"ERROR: Could not find a version that satisfies the requirement h3 (from versions: none)"},{"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))`.","cause":"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.","error":"TypeError: Invalid argument, not a string or column: DataFrame[...] of type <class 'pyspark.sql.dataframe.DataFrame'>"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.5.0","cli_name":"h3","cli_version":"sh: 1: h3: not found","type":"library","homepage":"https://h3geo.org","github":"https://github.com/uber/h3-py","docs":"https://uber.github.io/h3-py/","changelog":"https://uber.github.io/h3-py/_changelog.html","pypi":"https://pypi.org/project/h3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}