contextily

library1.7.0pypypi✓ verified 84d ago

Contextily is a Python library (v1.7.0) for adding context geo-tiles as basemaps to Matplotlib figures or saving them as geospatial raster files. It is actively developed, with minor releases every few months, and is tightly integrated with GeoPandas and the `xyzservices` package for tile providers.

data http-networking

pip install contextily

github ↗package ↗

INSTALL

IMPORT

SIG · CONTEXTILY

contextily

datapythonv1.7.0

Install

10.0s avg

Import

—

Disk

286MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.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

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 10.0s · import 0.000s · 284MB

286MB installed

● package 286MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

add_basemap

✓ from contextily import add_basemap

✗ import contextily as cx

This quickstart demonstrates how to use `contextily` with `geopandas` to add a web tile basemap to a geospatial plot. It loads the NYC boroughs dataset, reprojects it to Web Mercator (EPSG:3857) which is standard for web tiles, plots the data, and then overlays a basemap using `cx.add_basemap()`.

import geopandas import contextily as cx import matplotlib.pyplot as plt # Load a sample GeoDataFrame df = geopandas.read_file(geopandas.datasets.get_path("nybb")) # Ensure the data is in Web Mercator (EPSG:3857) or set the crs parameter in add_basemap df_wm = df.to_crs(epsg=3857) # Plot the GeoDataFrame fig, ax = plt.subplots(figsize=(10, 10)) df_wm.plot(ax=ax, alpha=0.5, edgecolor="k", facecolor="cyan") # Add a basemap cx.add_basemap(ax, crs=df_wm.crs) # Optional: Customize the title and display ax.set_title("NYC Boroughs with Contextual Basemap") plt.tight_layout() plt.show()

Debug

Known issues

breakingThe `plot_map` function was deprecated in previous versions and has been entirely removed in `contextily` v1.7.0.

fix

Use `contextily.add_basemap()` instead, which offers more flexibility and is the current recommended approach.

affects: >=1.7.0

breakingThe default tile provider changed from Stamen to OpenStreetMap Humanitarian in v1.4.0. This change was due to Stamen moving under Stadia and requiring an API key. Users expecting Stamen tiles will now get OpenStreetMap Humanitarian by default.

fix

If you need a specific tile provider, explicitly specify it using the `source` parameter in `add_basemap`, e.g., `source=cx.providers.CartoDB.Voyager`. For Stamen, you might need an API key and to specify the full URL.

affects: >=1.4.0

breakingContextily now requires Python 3.10 or newer. Older Python versions are no longer supported.

fix

Upgrade your Python environment to version 3.10 or higher.

affects: >=1.7.0

gotchaWeb map tiles are typically in Web Mercator (EPSG:3857). If your data is in a different Coordinate Reference System (CRS), you must either reproject your data to EPSG:3857 before plotting or pass your data's CRS to `cx.add_basemap` using the `crs` parameter for on-the-fly warping. Not doing so can lead to misaligned basemaps.

fix

Before `cx.add_basemap(ax, ...)`, ensure your GeoDataFrame is reprojected (`gdf.to_crs(epsg=3857).plot(ax=ax)`) or explicitly pass `crs=gdf.crs` to `add_basemap`.

affects: All versions

Upgrade

Version history

1.7.0latest on PyPI · released Nov 24, 2025

Audit

Dependencies

geopandasrequiredCrucial for integrating basemaps with geospatial vector data plotting.

matplotlibrequiredUsed for generating plots and providing the `AxesSubplot` object for basemap integration.

xyzservicesrequiredProvides the backend for managing and accessing various web tile providers.

rasteriorequiredUsed for reading local raster files and for warping/reprojection operations.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/geopandas/contextily ↗

packagehttps://pypi.org/project/contextily/ ↗