Install & Compatibility
Where this runs
tested against v1.1.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.95 runs
installs and imports cleanly · install 0.0s · import 1.028s · 178.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.5s · import 0.998s · 170MB
181MB installed
● package 181MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PolygonPatch
✓ from descartes import PolygonPatch
PointPatch
✓ from descartes import PointPatch
✗ from descartes.patch import PointPatch
While `descartes.patch` might work, the direct `descartes` import is the common and intended pattern.
LineStringPatch
✓ from descartes import LineStringPatch
This quickstart demonstrates how to create a `shapely.geometry.Polygon` and then render it on a Matplotlib axis using `descartes.PolygonPatch`. The `PolygonPatch` converts the geometric object into a displayable Matplotlib patch.
import matplotlib.pyplot as plt
from shapely.geometry import Polygon
from descartes import PolygonPatch
# Define a simple polygon using Shapely
polygon = Polygon([(0, 0), (1, 1), (0, 1), (0, 0)])
# Create a Matplotlib figure and axes
fig, ax = plt.subplots()
# Create a PolygonPatch from the Shapely Polygon
# You can customize color (fc), edge color (ec), alpha, etc.
patch = PolygonPatch(polygon, fc='blue', ec='black', alpha=0.5, zorder=2)
# Add the patch to the axes
ax.add_patch(patch)
# Set axes limits to display the polygon
minx, miny, maxx, maxy = polygon.bounds
ax.set_xlim(minx - 0.1, maxx + 0.1)
ax.set_ylim(miny - 0.1, maxy + 0.1)
ax.set_aspect('equal', adjustable='box') # Keep aspect ratio
plt.title("Shapely Polygon plotted with Descartes")
plt.show()
Debug
Known issues
breakingDescartes 1.1.0 is incompatible with Shapely versions 2.0 and newer. Using `PolygonPatch` (or other patches) with `Shapely >= 2.0` will result in an `IndexError: too many indices for array` due to changes in how Shapely exposes exterior/interior coordinates.fixDowngrade Shapely to a version less than 2.0 (e.g., `pip install 'Shapely<2.0'`) or consider migrating to a different plotting solution that natively supports newer Shapely versions, such as `matplotlib.patches.Polygon` directly, or libraries like GeoPandas (which has dropped descartes as a dependency).
affects: descartes 1.1.0 with Shapely >= 2.0
deprecatedThe Descartes library is no longer actively maintained; its last release was in January 2017. This means it will not receive updates for new features, bug fixes, or official compatibility with newer versions of Python or its dependencies (like Matplotlib or Shapely). Other libraries that previously relied on Descartes are migrating away from it.fixBe aware of potential compatibility issues. For new projects, consider using native Matplotlib patching capabilities with Shapely geometries or explore other maintained geospatial plotting libraries.
affects: All versions, especially when used with modern Python environments (Python 3.8+).
gotchaWhile Descartes handles basic geometric objects, for more complex GIS plotting needs (e.g., coordinate system transformations, basemaps), you will likely need to integrate it with other libraries like Matplotlib's Basemap or GeoPandas (though GeoPandas is moving away from Descartes).fixPlan for additional libraries for advanced geospatial plotting. Understand that Descartes primarily acts as a bridge between Shapely geometries and Matplotlib patches.
affects: All versions
Errors
Common errors & fixes
IndexError - Descartes PolygonPatch wtih shapely
The `descartes` library, due to its age (last updated 2017), expects `Shapely` geometries to expose coordinates directly via `.exterior`, but `Shapely` versions 2.0 and newer require `.exterior.coords` to access them, causing an `IndexError` when `descartes.PolygonPatch` attempts to plot.
fixDowngrade `Shapely` to a compatible older version, such as `shapely==1.8.5` or `shapely==1.7.0`, using `pip install 'shapely<2.0'`. Alternatively, one can manually edit the `descartes/patch.py` file (around line 62) in their Python environment to change `t.exterior` to `t.exterior.coords`.
ImportError: The descartes package is required for plotting polygons in geopandas.
This error occurs when trying to plot geometric objects, particularly polygons, using `geopandas` without the `descartes` library installed, as `geopandas` historically relied on `descartes` for this functionality.
fixInstall the `descartes` package using pip: `pip install descartes`.
ShapelyDeprecationWarning: The array interface is deprecated and will no longer work in Shapely 2.0. Convert the '.coords' to a numpy array instead.
This warning indicates that the `descartes` library is using an outdated method to access coordinate arrays from `Shapely` geometries, which has been deprecated in `Shapely` 2.0+ and will eventually lead to errors.
fixTo resolve the underlying incompatibility and prevent future errors, downgrade `Shapely` to a version below 2.0, for example: `pip install 'shapely<2.0'` or specifically `pip install shapely==1.8.5`. Alternatively, you can filter out the warning using `warnings.filterwarnings('ignore', category=ShapelyDeprecationWarning)` if you acknowledge the issue but cannot downgrade Shapely. Upgrade
Version history
1.1.0latest on PyPI · released Jan 17, 2017
Audit
Dependencies
matplotlibrequiredRequired for plotting geometric objects.
numpyrequiredUnderlying dependency for array operations.
ShapelyoptionalHighly recommended for creating geometric objects that Descartes plots. Version <2.0 is required for full compatibility with descartes 1.1.0.