# Cartopy for Python map visualization with Matplotlib

> Cartopy is a Python library for drawing projected maps and transforming points, lines, polygons, and images for Matplotlib. It suits scientific and GIS workflows, but it requires Python 3.11 or newer and includes a compiled extension.

**SciTools/cartopy** — Cartopy - a cartographic python library with matplotlib support

- Repository: https://github.com/SciTools/cartopy
- Website: https://cartopy.readthedocs.io/
- Stars: 1,622 · Forks: 403
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/scitools-cartopy

## Cartopy's mapping problem and scientific audience

Cartopy addresses the gap between ordinary Matplotlib axes and geographic coordinates. A Matplotlib plot treats its coordinates as drawing positions unless an application adds the projection and transformation machinery required for maps. Cartopy places that machinery inside the Matplotlib workflow, allowing developers to express cartographic output in Python rather than switch to a separate desktop GIS system.

The intended audience includes scientific Python developers, data analysts, and GIS engineers who need map figures as part of plots, reports, notebooks, or reproducible analysis. The project metadata identifies scientific computing, GIS, and visualization as relevant application areas. The library is not presented as a general data-management application or a map tile viewer. It focuses on drawing maps and transforming spatial data for display.

This positioning makes Cartopy useful when a figure needs coastlines, boundaries, projected coordinates, graticules, or other map context. It also fits code that already depends on Matplotlib and NumPy. Cartopy may be less suitable when the primary requirement is an interactive desktop GIS, a browser map, or turnkey tile delivery. The README does not describe such applications as Cartopy features, so treating it as a replacement for them would be a category error.

## Projection objects and transformed Matplotlib geometry

The core mechanism described by the README is a set of object-oriented projection definitions. Cartopy does not merely attach a map image to an axes. It provides a coordinate system through which geographic geometry can be transformed for display. This distinction matters because longitude and latitude are not the same drawing space as the coordinates used by a chosen map projection.

Cartopy supports transformations for points, lines, polygons, and images. That range reflects common layers in cartographic plotting. Points can represent locations, lines can represent routes or boundaries, polygons can represent regions, and images can carry raster content. The README also states that this mapping functionality is exposed through Matplotlib with a simple interface, so Cartopy's projection machinery is designed to participate in the existing figure and axes model rather than bypass it.

Based on the repository layout, the implementation is more than a thin Python wrapper. The `lib/cartopy/` directory contains the library, while `setup.py` declares a C++ extension named `cartopy.trace`, sourced from `lib/cartopy/trace.pyx` when Cython is used. Both Cython source builds and source distributions compile the corresponding Cython or C++ implementation. This compiled component is an adoption consideration for environments that restrict native builds.

## Vector data through Shapely and shapefile handling

Cartopy's vector-data path combines map drawing with Shapely capabilities. The README specifically identifies shapefile reading as integrated functionality. This puts Cartopy closer to geospatial visualization than a basic plotting helper: a workflow can involve reading vector features, working with their geometries, and drawing them within a projected Matplotlib figure.

The dependency metadata requires `shapely>=2.0`, while the `pyproject.toml` keywords include `shapefile` and `pyproj`. The repository description also names geometry and projections as project topics. Together, these sources establish that Cartopy is designed around spatial geometry and coordinate transformation rather than decorative basemap composition alone.

There is an important boundary in the documentation. The README does not describe automatic dataset downloads, included coastlines, bundled administrative boundaries, or a catalog of ready-made map features. The documentation and `examples/vector_data/` directory are the stated places to investigate vector examples, but the README does not promise that any particular dataset is installed. A user who expects `import Cartopy` to provide complete world boundaries would be assuming behavior that the README does not document.

Shapefile licensing and provenance also remain external concerns. The README explains Cartopy's own BSD-3-Clause license, but it does not identify licenses for every map asset that a separate workflow might consume. Project adoption therefore does not by itself settle whether a particular coastline, country boundary, or raster image can be redistributed with generated output.

## Platform requirements and installation documentation

The repository metadata gives concrete compatibility requirements. Cartopy requires Python `>=3.11` and is classified for Python 3.11, 3.12, 3.13, and 3.14. Supported operating-system classifiers include macOS, Windows, POSIX, AIX, and Linux, although those classifiers describe intended packaging rather than a guarantee that every installation method works everywhere.

Runtime dependencies shown in `pyproject.toml` include `numpy>=1.26`, `matplotlib>=3.8`, and `shapely>=2.0`. A source build additionally declares `Cython >= 3.0`, `numpy>=2.0.0`, and `setuptools >= 77.0.3` in its build requirements. `setup.py` checks for Cython when building from source and compiles the `cartopy.trace` extension as C++.

The README links to the online documentation, and the repository contains an `INSTALL` file. Their installation contents are not reproduced here. The README gives no exact package-manager command, wheel platform, or platform-specific build procedure. It would be misleading to invent a command such as `pip install Cartopy`. For a first installation, consult the linked documentation and `INSTALL`, select a distribution method that fits the environment, and confirm that the declared Python and dependency constraints are satisfied before attempting a map script.

## A first-use path through projections and Matplotlib

Cartopy has no documented command-line workflow in the README, so the first real use is a Python and Matplotlib task rather than a CLI operation. Start with the stable documentation linked as `https://cartopy.readthedocs.io/stable/`, choose an example matching the layer you need, and create a Matplotlib figure using Cartopy's projection interface. The documentation's examples should define the exact current imports and axes construction because the README does not provide a complete runnable script.

A practical evaluation should cover more than an empty projected axes. First create a figure and select a documented projection. Then add one feature that exercises the intended data path, such as a point, line, polygon, image, or shapefile-backed vector layer. Save the figure only after confirming that the geometry appears at the expected geographic positions and within the intended map extent. The repository's `examples/gridlines_and_labels/`, `examples/lines_and_polygons/`, `examples/scalar_data/`, and `examples/vector_data/` directories provide targeted areas for finding such workflows.

No code example is reproduced here because the README and repository excerpts do not show an import path or a complete plotting call. Copying an example from the stable documentation is safer than inventing API names. That first test also reveals whether the target environment can install the native extension and whether the required external map assets are already available.

## Release cadence, native builds, and BSD-3-Clause implications

Cartopy is not archived, and the last push was on 2026-10-14. The recorded releases include v0.26.0 on 2026-09-17, v0.25.0 on 2025-08-01, and v0.24.1 on 2024-10-08. These dates indicate recent release activity, although the repository metadata does not set a fixed support policy or promise compatibility across every release.

Upgrade planning has two layers. The first is Python and numerical-library alignment. A move to a newer Python or NumPy version can interact with Matplotlib, Shapely, wheels, or native compilation. The second is the map-data workflow. The README does not document a rollback procedure, compatibility matrix for external map assets, or a cache migration guide, so those points should not be assumed.

Cartopy is released under the BSD-3-Clause license, with a shared copyright model and contributions including British Crown copyright through the Met Office. That license governs the project's code. It does not automatically grant rights in third-party shapefiles, images, coastlines, or other data loaded by an application. This distinction matters especially when generated maps are published or redistributed. Review the exact data license separately from the library license, without treating the library license as legal advice about those assets.

## Matplotlib-native Cartopy versus GIS-focused alternatives

Cartopy's clearest alternative is a GIS-focused Python workflow built around a separate geospatial data and mapping stack, rather than Matplotlib. The difference is not that one system can draw a map and the other cannot. It is where map rendering sits in the application and which abstractions dominate the API.

A GIS-focused alternative may center workflows on geodetic datasets, feature inspection, spatial queries, and desktop-style map composition. Cartopy centers cartographic projection and drawing inside Matplotlib, which is useful when existing code already builds figures and axes, when the output should fit a Python visualization pipeline, or when the desired artifact is a static or notebook-oriented map figure. Cartopy's documented feature set directly addresses projection definitions, geometry transformations, Matplotlib integration, and shapefile reading.

Choose Cartopy when the map is part of a scientific Matplotlib visualization and the application supplies or retrieves its geographic features. Do not choose it merely because it can transform coordinates if you also need an undocumented interactive GIS interface, comprehensive tile management, or a turnkey data browser. Cartopy also introduces a native build and dependency boundary that a pure Python plotting arrangement may avoid, although prebuilt distribution availability is not specified in the repository files.

## Conclusion

Cartopy fits engineers who already work in Python and need projected map figures rather than a standalone GIS application. It is a poor fit for Python versions below 3.11, environments without compiled-extension support, or workflows requiring an undocumented command-line interface or automatic map-data acquisition. Before adoption, verify that the intended map images and shapefiles are available under terms suitable for your project, then confirm compatibility with your required Python, NumPy, Matplotlib, and Shapely versions. For a Matplotlib-centered first evaluation, verify the installation procedure in `INSTALL` and the stable documentation before writing rendering code.

## FAQ

### What is Cartopy used for?

Cartopy is a Python package for drawing maps for data analysis and visualization. It provides projection definitions, spatial transformations, Matplotlib integration, and vector-data handling through Shapely.

### Does Cartopy work with Matplotlib?

Yes. Cartopy integrates with Matplotlib through the Matplotlib figure and axes workflow, and its `pyproject.toml` declares `matplotlib>=3.8` as a runtime dependency.

### What Python version and dependencies does Cartopy require?

Cartopy requires Python `>=3.11`. Its declared runtime dependencies include `numpy>=1.26`, `matplotlib>=3.8`, and `shapely>=2.0`; source builds also involve Cython and a compiled `cartopy.trace` extension.

## Sources

- [License: BSD-3-Clause](https://github.com/SciTools/cartopy/blob/main/LICENSE)
- [Project website](https://cartopy.readthedocs.io/)
- [README](https://github.com/SciTools/cartopy/blob/main/README.md)
- [Releases](https://github.com/SciTools/cartopy/releases)
- [SciTools/cartopy on GitHub](https://github.com/SciTools/cartopy)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/scitools-cartopy