contextily fetches map tiles and drops them under a matplotlib figure

A basemap in one call, in either of the two coordinate systems

The problem contextily solves is narrow and real. Drawing a polygon map in matplotlib means you have geometry, but you have no context, so the reader sees shapes floating on white. Filling that white with map tiles is tedious by hand, and contextily does it in a single call. The package is described as a small Python 3 package, 3.10 and above, to retrieve tile maps from the internet, and it can do two things with them: add the tiles as a basemap to matplotlib figures, or write tile maps to disk into geospatial raster files. That second capability is the one that surprises people, because a tile mosaic written out as a GeoTIFF or similar is a map image you can use anywhere, not just inside a figure. Bounding boxes can be passed in both WGS84, EPSG:4326, and Spheric Mercator, EPSG:3857, which is the projection the tile services themselves use, and handling both is what lets the package line up tiles with data that is in either.

Tile providers come from xyzservices, not from contextily

The provider story is the part to understand first, because it shapes what the package can and cannot do. The current tile providers available in contextily are the providers defined in the xyzservices package, and that includes some popular tile maps such as the standard OpenStreetMap map tiles and the Toner, Terrain and Watercolor tiles by Stamen Design. So contextily does not contain a list of tile servers, it consumes one, and the catalogue of what you can draw from is the catalogue that xyzservices maintains. That is a good separation. A provider definition carries the URL template, the tile size, the zoom range and the attribution, and treating those as data rather than code means a new provider does not need a contextily release. It also means the practical limits are the provider's, both in terms of what imagery exists at which zoom level and in terms of what you are allowed to do with the tiles.

Installing is a pip or conda line, on Python 3.10 or newer

The install is short because the package is a thin layer. The latest released version is installed with pip.

pip3 install contextily

The conda route is the alternative.

conda install contextily

Python 3 only, 3.10 and above, is stated in the installation section, and the packaging metadata agrees, with requires-python set to >=3.10 and classifiers for Python 3.10 through 3.14. The dependency list is longer than the package itself, which is worth seeing. In the README the dependencies are mercantile, numpy, matplotlib, pillow, rasterio, requests, geopy, joblib and xyzservices, while the pyproject list is the same set without numpy spelled out, since numpy arrives through the others. The two names that explain the design are mercantile, which does the slippy map tile maths of turning a coordinate into a tile address, and rasterio, which is the geospatial raster library that makes writing tiles to disk possible rather than a novelty. The package is built with setuptools and setuptools_scm, so the version is derived from the git tags rather than written in a file.

The usage guide is a notebook, and the docs site is the reference

The README points at a notebook for usage, the contextily_guide.ipynb file, and the project publishes its documentation on readthedocs at contextily.readthedocs.io. The repository layout shows both halves of the project. There is a notebooks directory alongside a docs directory, and a Dockerfile that builds a working environment with the package installed from the main branch of the git repository rather than from PyPI, along with the notebooks copied into the home directory. The base image is a Geospatial Data Science image, darribas/gds_py:4.1, and the package is installed with pip install -U earthengine-api and the git URL for contextily at main. That image is the reason a Binder badge appears at the top of the README, and it means you can open the project in a hosted notebook environment with the package and its dependencies already resolved. For your own use, though, the plain pip install is the supported path, and the Dockerfile is aimed at development and demonstration rather than at deployment.

Rasters on disk are the capability the plotting API does not advertise

Most people meet contextily through the basemap feature, and the disk-writing feature is easy to overlook. The documentation describes it as writing tile maps to disk into geospatial raster files, and the significance is that a raster written with a bounding box and a projection is a real geospatial artifact rather than a screenshot. It carries the projection of the tile service, so it can be reprojected and overlaid on vector data with the usual geospatial tooling, and it can be a background layer in a figure you assemble later. The practical constraint is that the tiles are fetched over the network for every tile in the mosaic, which is where the network dependency stops being a convenience and becomes a rate limit and a runtime concern. For a small figure at a city zoom level that is a handful of requests. For a country at high zoom it is thousands, and the package has a requests-based fetcher with no mention of an API key mechanism, because the free tile services do not use keys but do apply their own policies.

Tile usage policy is the constraint the package cannot enforce

This is the practical point that the README does not dwell on, and it is where a user can get into trouble. The tile maps contextily offers by default, the standard OpenStreetMap tiles, are published by the OpenStreetMap Foundation, and the project documentation lists the Stamen Design Toner, Terrain and Watercolor tiles as additional options. Every tile service in the xyzservices catalogue carries a usage policy, and the free ones exist for casual and moderate use, not for serving a production application to many users. The contextily use case, pulling a few hundred tiles to draw one figure, is exactly the use these services are meant for. A pipeline that renders thousands of figures per day from the same public endpoint is not. The distinction contextily itself draws is between the package and the provider, which is helpful for understanding where responsibility sits but does not change the terms you have agreed to with the tile operator.

Where contextily is the wrong tool

The first wrong case is a production web service that renders maps for end users, because every figure becomes an outbound request to a third party tile server on the critical path of someone else's page load. The second wrong case is offline or air-gapped work, since the package retrieves tiles from the internet and the documentation does not describe a local tile cache or an offline mode, so the basemap simply will not appear without connectivity. The third is a project that needs imagery rather than a map background, since contextily offers vector cartography, and satellite or terrain imagery is a different service with different terms. The fourth is a workflow that already has a map. If your data is in a GIS stack with its own rendering, or in a plotting library with its own tile support, adding contextily duplicates a capability rather than adding one. The fifth is anyone who needs the provider list to be stable, because the catalogue lives in xyzservices and can change independently of contextily releases, so a provider that works today may be renamed or withdrawn tomorrow without a version bump in this package.

How contextily compares with building the mosaic yourself

The alternative is to assemble the tile mosaic yourself, and the difference in approach is instructive. Doing it by hand means computing the tile range that covers your bounding box, fetching each tile over HTTP, stitching them into a single image with the right pixel dimensions, and then reprojecting that image into the coordinate system of your data before drawing it behind the plot. That is a few dozen lines with mercantile and PIL, which contextily itself depends on, and it is entirely reasonable to write. What you gain from the package is the parts that are easy to get subtly wrong: the correct tile range for a bounding box that spans the antimeridian or a zoom level where the tiles are indexed differently, the resampling when the tile grid and your data grid do not line up, and the colour and extent matching between the image and the axes limits. Against a general purpose mapping library that renders the map for you, contextily is a different thing entirely, since it hands you the tiles as an image and leaves the cartography to you.

Editorial conclusion

Geospatial analysts who plot data in matplotlib and want a recognisable basemap underneath it are the people contextily is for, and the fact that it also writes tile mosaics to disk as geospatial rasters makes it useful beyond the plotting case, for instance when building a static map image for a report. It is the wrong tool for a production pipeline that cannot depend on a third party tile server being up, and it is the wrong tool for offline work, since the package retrieves tiles from the internet. Check three things before you build on it: which tile provider you point it at, because the set of providers is defined by the xyzservices package rather than by contextily itself, whether your provider permits the use you are making of the tiles, since the standard OpenStreetMap tiles come with a usage policy and the Stamen Design tiles named in the documentation are a separate arrangement, and that your plotting axis is in a coordinate system the package can reason about, since bounding boxes can be passed in WGS84 or in Spheric Mercator. The licence is BSD-3-Clause, the newest release is v1.7.1 from 2026-07-10, and the last push was on 2026-07-27.

Frequently asked questions

Official sources

1. geopandas/contextily on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases