Install & Compatibility
Where this runs
tested against v2.1.2 · 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
py 3.9
✕ build_error
✓ 4.9s
101MB installed
● package 101MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Point
✓ from shapely import Point
Polygon
✓ from shapely import Polygon
box
✓ from shapely import box
shapely.geometry.Point
✓ from shapely.geometry import Point
✗ import shapely.geometry.Point
Geometry subclasses are now available directly in the top-level `shapely` namespace (since 2.0), making `from shapely import Point` the preferred modern import. `from shapely.geometry import Point` still works for individual geometry types.
shapely.geos
✓ from shapely import GEOS_VERSION
✗ import shapely.geos
The `shapely.geos` module is deprecated in 2.1.x; GEOS-version related attributes are now directly available from the top-level `shapely` namespace (e.g., `shapely.GEOS_VERSION`).
shapely.vectorized.contains
✓ from shapely import contains_xy
✗ from shapely.vectorized import contains
The `shapely.vectorized` module is deprecated in 2.1.x. Use top-level vectorized functions like `shapely.contains_xy` and `shapely.intersects_xy` instead.
This quickstart demonstrates creating basic `Point` and `Polygon` geometries and performing a simple spatial intersection. It also includes an example of a vectorized operation using NumPy arrays, a key performance feature introduced in Shapely 2.0.
import shapely
from shapely import Point, Polygon
# Create a point and a polygon
point = Point(0, 0)
polygon = Polygon([(0, 0), (1, 1), (1, 0)])
# Perform a spatial operation
intersection = point.intersection(polygon)
print(f"Point: {point}")
print(f"Polygon: {polygon}")
print(f"Intersection: {intersection}")
print(f"Point within polygon: {polygon.contains(point)}")
# Example of a vectorized operation (Shapely 2.0+)
import numpy as np
geoms = np.array([Point(0.5, 0.5), Point(1.5, 0.5)])
print(f"\nVectorized contains: {shapely.contains(polygon, geoms)}")
Debug
Known issues
breakingShapely 2.0 introduced a complete internal refactor (merging PyGEOS), making geometries immutable and changing how multi-part geometries behave.fixGeometries are now immutable and hashable; do not attempt in-place modification. For multi-part geometries (e.g., `MultiPolygon`), they are no longer sequence-like (no `len()`, not iterable, not indexable) – use the `.geoms` attribute to access individual parts.
affects: 2.0.0+
breakingDirect conversion of geometry objects to NumPy arrays (`np.asarray(geom)`) is deprecated and removed in 2.0.fixUse `np.asarray(geom.coords)` to convert geometry coordinates to a NumPy array.
affects: 2.0.0+
breakingThe `STRtree` API changed significantly in Shapely 2.0. Operations now return indices of input geometries instead of the geometries themselves.fixReview the `STRtree` documentation for the updated `query()` method, which merges `query()` and `query_bulk()` and directly includes predicate evaluation.
affects: 2.0.0+
deprecatedMany function parameters, especially boolean flags like `normalized` or `include_z`, are being transitioned to keyword-only arguments. Passing them positionally is deprecated and raises warnings.fixAlways pass such parameters as keyword arguments (e.g., `geom.buffer(distance, quad_segs=16)` instead of `geom.buffer(distance, 16)`).
affects: 2.1.0+
gotchaWhen installing Shapely in a Conda environment, installing via `pip install shapely` can sometimes lead to issues with GEOS library discovery, potentially bundling an outdated GEOS.fixAlways install Shapely via `conda install shapely --channel conda-forge` when using Conda to ensure proper GEOS linking.
affects: All versions in Conda environments.
gotchaShapely is a planar geometry library; Z coordinates are generally ignored in geometric analysis, and geometries differing only in Z are not distinguished. `LineString([(0, 0, 0), (0, 0, 1)])` results in an invalid line with zero length.fixBe aware that Shapely's core operations are 2D. While geometries can store Z/M values (especially since 2.1.0), most analytical methods primarily use X and Y coordinates. Validate your geometry inputs to avoid unexpected behavior with Z differences.
affects: All versions
Upgrade
Version history
2.1.2latest on PyPI · released Sep 24, 2025
Audit
Dependencies
GEOSrequiredShapely wraps the GEOS C++ library; it is dynamically linked. Binary wheels bundle GEOS, but source installs or specific environments might require manual GEOS installation/discovery.
numpyrequiredRequired for vectorized (ufunc) operations and integration with array-like data, especially since Shapely 2.0.