Install & Compatibility
Where this runs
tested against v0.2.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.359s · 202MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.7s · import 0.306s · 176MB
185MB installed
● package 185MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
geoarrow.pyarrow
✓ import geoarrow.pyarrow as ga
✗ from geoarrow import pyarrow as ga
The primary module for GeoArrow PyArrow functionality.
geoarrow.pyarrow.types
✓ import geoarrow.pyarrow.types as gat
For accessing specific GeoArrow type constructors and definitions.
This quickstart demonstrates how to create a GeoArrow array from a list of Shapely geometries, inspect its type and contents, convert it back to Shapely, and integrate it into a PyArrow Table. It highlights the use of the `ga.array()` constructor for data conversion.
import geoarrow.pyarrow as ga
import shapely.geometry
import pyarrow as pa
# Create some Shapely Point geometries
points = [
shapely.geometry.Point(1, 2),
shapely.geometry.Point(3, 4),
shapely.geometry.Point(5, 6)
]
# Convert Shapely geometries to a GeoArrow array using the unified constructor
geoarrow_array = ga.array(points)
print("GeoArrow Array Type:", geoarrow_array.type)
print("GeoArrow Array:", geoarrow_array)
# You can also convert it back to Shapely objects
shapely_roundtrip = geoarrow_array.to_shapely()
print("Shapely Roundtrip:", shapely_roundtrip)
# Integrate GeoArrow arrays into a PyArrow Table
table = pa.table({'id': [1, 2, 3], 'geometry': geoarrow_array})
print("\nPyArrow Table:")
print(table)
# It's crucial to register extension types when loading data from disk
# if the data contains GeoArrow types.
# ga.register_extension_types() # Uncomment if loading from file
Debug
Known issues
breakingThe GeoArrow PyArrow API underwent significant changes in version 0.2.0. Functions like `from_shapely`, `from_wkb`, and direct module-level constructors were replaced or consolidated.fixUpdate your code to use the new unified `geoarrow.pyarrow.array()` constructor for most conversions from Python objects (Shapely, WKB, lists of coordinates). For advanced construction, refer to `geoarrow.pyarrow.construct`.
affects: from 0.1.x to 0.2.0
gotchaGeoArrow itself is a data format for geometries and does not embed Coordinate Reference System (CRS) information. This is similar to how PyArrow handles non-semantic types.fixManage CRS information explicitly in your application layer (e.g., using `geopandas` or other geospatial libraries). Ensure consistent CRS when combining or processing GeoArrow data.
affects: All versions
gotchaWhen loading data from files (e.g., Parquet, Feather) that contain GeoArrow extension types, you must register these types *before* reading the file. Otherwise, PyArrow will not recognize them and might load them as generic binary or list types.fixCall `geoarrow.pyarrow.register_extension_types()` at the start of your script or before any read operations that might contain GeoArrow data.
affects: All versions
gotchaGeoArrow PyArrow has a strict dependency on `pyarrow >= 10.0`. Using an older version of PyArrow will likely result in `ImportError` or runtime crashes due to ABI incompatibilities.fixEnsure your environment has `pyarrow` version 10.0 or higher. You can upgrade with `pip install --upgrade pyarrow`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'geoarrow'
The `geoarrow-pyarrow` package is not installed or not available in the current Python environment.
fixInstall the package using pip: `pip install geoarrow-pyarrow`
ImportError: cannot import name 'from_shapely' from 'geoarrow.pyarrow' (...)
Attempting to use the `0.1.x` API (e.g., direct `from_shapely` or `from_wkb` functions) with `geoarrow-pyarrow` version `0.2.0` or newer.
fixUpdate your code to use the new unified `geoarrow.pyarrow.array()` constructor. For example, `ga.array(shapely_geometries)` or `ga.array(wkb_bytes_list)`.
pyarrow.lib.ArrowInvalid: Could not find GeoArrow extension type for geoarrow.point.xy (or similar for other types)
Attempting to read a file (e.g., Parquet, Feather) containing GeoArrow extension types without registering them first in the current Python session.
fixCall `geoarrow.pyarrow.register_extension_types()` at the beginning of your script, before any file read operations that might involve GeoArrow data.
ImportError: geoarrow.pyarrow requires pyarrow >= 10.0.0, but you have 9.0.0 (or similar version mismatch)
The installed `pyarrow` version is older than the minimum required by `geoarrow-pyarrow`.
fixUpgrade `pyarrow` to version 10.0 or higher: `pip install --upgrade pyarrow`
Upgrade
Version history
0.2.0latest on PyPI · released May 27, 2025
Audit
Dependencies
pyarrowrequiredCore dependency for Arrow data structures and C++ bindings.
shapelyrequiredUsed for conversion to and from common Python geospatial objects.
numpyoptionalOptional dependency for certain array operations or input types.
pandasoptionalOptional dependency for DataFrame integration.
geopandasoptionalOptional dependency for more advanced geospatial data handling.