PyGEOS

Common errors

• ModuleNotFoundError: No module named 'pygeos'

  cause The 'pygeos' Python package is not installed in the active virtual environment.
  fix Run `pip install pygeos`.

• pygeos.GEOSException: Could not find GEOS shared library

  cause The underlying GEOS C library, essential for PyGEOS functionality, is not installed on the system or is not discoverable by Python.
  fix Install the GEOS C library using your system's package manager (e.g., `sudo apt-get install libgeos-dev` on Debian/Ubuntu, `brew install geos` on macOS, or `conda install -c conda-forge pygeos` if using Anaconda/Miniconda).

• TypeError: ufunc 'contains' not supported for the input types

  cause Attempting to use a PyGEOS ufunc with incompatible input types, often by mixing `pygeos` geometries with `shapely` 1.x geometries or other non-geometry types without conversion.
  fix Ensure all geometry inputs to `pygeos` functions are `pygeos` geometry objects. If working with Shapely 1.x, convert geometries using `pygeos.from_shapely()` before passing them to `pygeos` functions. Consider migrating to Shapely 2.x for unified geometry handling.

Warnings

• breaking PyGEOS is officially deprecated as its core functionality has been merged into Shapely 2.0+. No new major features or releases are expected. New projects should use Shapely 2.x, and existing projects should plan to migrate.
  Fix: For new projects, use `shapely` (install `pip install shapely`). For existing projects, refer to the Shapely 2.0 migration guide for `pygeos` users (e.g., `shapely.from_pygeos()`, `shapely.to_pygeos()`).
• gotcha PyGEOS requires the GEOS C library (>= 3.5.0, preferably >= 3.6.0 for full features) to be installed on your system. `pip install pygeos` only installs the Python bindings, not the underlying C library. Failure to install GEOS will result in runtime errors.
  Fix: Install GEOS via your system's package manager (e.g., `sudo apt-get install libgeos-dev` on Ubuntu, `brew install geos` on macOS) or through a package manager like Conda (`conda install -c conda-forge pygeos`).
• gotcha PyGEOS objects are distinct from Shapely 1.x objects. Direct interoperation between them without explicit conversion methods (e.g., `pygeos.from_shapely`, `shapely.to_pygeos`) can lead to `TypeError` or unexpected behavior.
  Fix: Convert geometries between the libraries using `pygeos.from_shapely()` or `shapely.to_pygeos()` when necessary. For a unified approach, migrate to Shapely 2.x, which uses the same internal geometry representation.
• gotcha Optimal performance in PyGEOS is achieved by leveraging its vectorized ufuncs, which expect NumPy arrays of geometries or coordinates as input. Iterating over scalar PyGEOS geometries in Python loops negates much of the performance benefit.
  Fix: Always pass NumPy arrays of geometries or coordinate arrays directly to `pygeos` functions for best performance. For example, `pygeos.area(geometry_array)` instead of `[pygeos.area(g) for g in geometry_list]`.

Install

• pip install pygeos Install PyPI package

Imports

• pygeos

  import pygeos

Quickstart

Demonstrates creating basic geometry objects (points, polygon) and performing a vectorized spatial operation (intersects).

import pygeos

# Create a single point
point_a = pygeos.points(0, 0)

# Create an array of points
points_array = pygeos.points([
    [1, 1],
    [2, 2],
    [3, 3]
])

# Create a polygon
polygon = pygeos.polygons([(0, 0), (0, 4), (4, 4), (4, 0), (0, 0)])

# Perform a spatial operation: check intersection
intersects = pygeos.intersects(polygon, points_array)

print(f"Point A: {point_a}")
print(f"Points array: {points_array}")
print(f"Polygon: {polygon}")
print(f"Intersects with polygon: {intersects}") # Expected: [True, True, True]