Install & Compatibility
Where this runs
tested against v2.1.0.20260728 · 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
92MB installed
● package 92MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Point
✓ from shapely-stubs import Point
✗ from shapely.geometry import Point
This quickstart demonstrates how to use `types-shapely` to enable static type checking for `shapely` code. After installing `shapely` and `types-shapely`, you can write your Python code with type annotations for Shapely objects. A type checker like MyPy will then use the provided stubs to validate your code.
import sys
import os
# Ensure shapely and types-shapely are installed
# For demonstration, we use a mock shell command
# In a real scenario, these would be in requirements.txt or pre-installed
if os.environ.get('SKIP_INSTALL', 'false').lower() != 'true':
# This part is for demonstration only to show expected installs.
# In a real environment, you'd just install via pip before running mypy.
# Example of how you'd install (not executed directly here for safety):
# print("Installing shapely and types-shapely (mock)...\n")
# os.system(f'{sys.executable} -m pip install shapely types-shapely mypy')
pass
from shapely.geometry import Point, Polygon
from typing import List, Tuple
def create_and_buffer_point(x: float, y: float, radius: float) -> Polygon:
"""Creates a point and buffers it."""
point: Point = Point(x, y)
buffered_polygon: Polygon = point.buffer(radius)
return buffered_polygon
def get_polygon_area(poly: Polygon) -> float:
"""Returns the area of a polygon."""
return poly.area
# Example usage
my_point = Point(0.0, 0.0)
my_polygon = create_and_buffer_point(0.0, 0.0, 10.0)
area = get_polygon_area(my_polygon)
print(f"Original point: {my_point}")
print(f"Buffered polygon: {my_polygon}")
print(f"Polygon area: {area}")
# To run type checking using mypy:
# 1. Save the above code as `main.py`
# 2. Ensure `shapely`, `types-shapely`, and `mypy` are installed:
# `pip install shapely types-shapely mypy`
# 3. Run mypy from your terminal:
# `mypy main.py`
# Expected output (if no type errors):
# `Success: No issues found in 1 source file`
Debug
Known issues
gotchaEnsure the version of `types-shapely` is compatible with your installed `shapely` version. `types-shapely` is typically tied to major/minor versions (e.g., `2.1.*`) of the `shapely` library it types. Using mismatched versions can lead to incorrect type checking results.fixAlways install `types-shapely` alongside a compatible `shapely` version, e.g., `pip install 'shapely==2.1.*' types-shapely`. Check the `types-shapely` PyPI page for the specific `shapely` version it aims to annotate.
affects: All versions of `types-shapely` (in relation to `shapely`)
breakingShapely 2.0 introduced significant changes, making geometries immutable and hashable. Code that mutates geometry objects in-place or relies on them being sequences (e.g., iterating over `MultiPolygon` directly) will break. `types-shapely` reflects these API changes.fixReview Shapely's migration guide for versions 1.8 to 2.0. Instead of in-place mutation, create new geometry objects. For multi-part geometries, use the `.geoms` property for iteration.
affects: Shapely >= 2.0 (and types-shapely for these versions)
deprecatedThe `.type` attribute on Shapely geometry objects is deprecated and will be removed. Use `.geom_type` instead.fixReplace all instances of `geometry.type` with `geometry.geom_type`.
affects: Shapely >= 2.0.0 (and types-shapely for these versions)
gotchaWhen accessing coordinates (e.g., `polygon.exterior.coords`), type checkers might infer generic `Tuple[float, ...]` which could be `Tuple[float, float]` or `Tuple[float, float, float]` depending on the presence of Z-coordinates. If your code assumes a 2D tuple but Z-coordinates are possible, type errors might occur.fixIf you are certain about the dimensionality, use `typing.cast` for explicit type assertion (e.g., `cast(List[Tuple[float, float]], polygon.exterior.coords)`). Alternatively, handle 2D and 3D coordinates explicitly in your logic.
affects: All versions of `types-shapely` (in relation to `shapely`)
breakingIn Shapely 2.0+, the creation of empty geometries is consistent, returning an empty geometry of the specified type (e.g., `Polygon()`) rather than an empty `GeometryCollection`. Code that relies on empty geometries always being `GeometryCollection` will be incorrect.fixDo not rely on empty geometries being `GeometryCollection`. Use the `.is_empty` attribute for robustly checking if a geometry object is empty.
affects: Shapely >= 2.0.0 (and types-shapely for these versions)
Upgrade
Version history
2.1.0.20260728latest on PyPI · released Jul 28, 2026
Audit
Dependencies
shapelyrequiredProvides type annotations for this library; typically, types-shapely should match the major/minor version of shapely (e.g., 2.1.*).