Migration from PyGEOS geometry backend to Shapely 2.0#
Since the 0.8 version, GeoPandas includes an experimental support of PyGEOS as an alternative geometry backend to Shapely. Recently, PyGEOS codebase was merged into the Shapely project and released as part of Shapely 2.0. GeoPandas will therefore deprecate support of the PyGEOS backend and will go forward with Shapely 2.0 as the only geometry engine exposing GEOS functionality.
Given that historically the PyGEOS engine was automatically used if the package is installed (this behaviour will changed in GeoPandas 0.14 where Shapely 2.0 is used by default if installed), some downstream code may depend on
PyGEOS geometries being available as underlying data of a
This guide outlines the migration from the PyGEOS-based code to the Shapely-based code.
The migration is planned for three releases spanning approximately one year, starting with 0.13 released in the second quarter of 2023.
PyGEOS is still used as a default backend over Shapely (1.8 or 2.0) if installed, with a
FutureWarningwarning about upcoming changes.
The default backend is Shapely 2.0 and the PyGEOS is used only if Shapely 1.8 is installed instead of 2.0 or newer. The PyGEOS backend is still supported, but a user needs to opt in using the environment variable
USE_PYGEOSas explained in the installation instructions.
GeoPandas will remove support of both PyGEOS and Shapely<2.
How to prepare your code for transition#
If you don’t use PyGEOS explicitly, there nothing to be done as GeoPandas internals will
take care of the transition. If you use PyGEOS directly and access an array of PyGEOS
GeoSeries.values.data, you will need to make some changes to avoid
The recommended way is using Shapely vectorized operations on the
instead of accessing the NumPy array of geometries and using PyGEOS/Shapely operations
on the array.
This is a common pattern used with GeoPandas 0.12 (or earlier), that should now be avoided in new code:
>>> import pygeos
>>> geometries = gdf.geometry.values.data
>>> mrr = pygeos.minimum_rotated_rectangle(geometries)
The recommended way of refactoring this code would look like this (with Geopandas 0.12 or later):
>>> import shapely # shapely 2.0
>>> mrr = shapely.minimum_rotated_rectangle(gdf.geometry.array)
This code will work no matter which geometry backend GeoPandas actually uses, because on
GeometryArray level, it always returns Shapely geometry. Although keep in mind, that
it may involve additional overhead cost of converting PyGEOS geometry to Shapely
Note that while in most cases, a simple replacement of
together with a change of
gdf.geometry.array should work, there are some differences between the
API of PyGEOS and that of Shapely. Please consult the
Migrating from PyGEOS
document for details.