Cartopy is a Python package designed for geospatial data processing and cartographic visualizations, building on Matplotlib. It provides object-oriented projection definitions, transformations between various map projections, and powerful vector data handling. The library is currently at version 0.25.0 and maintains an active release cadence, frequently updating to support modern Python and geospatial libraries.
pip install cartopyVerified import paths — ran on the pinned version, not inferred.
This quickstart creates a basic global map using the Plate Carree projection, adding standard geographical features such as land, ocean, coastlines, country borders, lakes, and rivers. It demonstrates the typical import pattern and usage of `add_subplot` with a Cartopy projection and `add_feature` for geographical elements.
Upgrade your Python environment to version 3.10 or newer.
Replace calls like `ax.natural_earth_shp('110m', 'coastline')` with `ax.add_feature(cfeature.COASTLINE)`. Check `cartopy.feature` for other available features.Use the replacement attributes: `Gridliner.top_labels`, `bottom_labels`, `left_labels`, or `right_labels`.
For path conversion, use `cartopy.mpl.path.path_to_shapely` and `cartopy.mpl.path.shapely_to_path`. If `clip_path` functionality is needed, consider vendoring it or finding alternative Matplotlib utilities.
If `pip install cartopy` fails, try `conda install -c conda-forge cartopy`. For pip, ensure development headers for GEOS and PROJ are installed on your system. Also, ensure `shapely>=2.0` for Cartopy v0.25+.
Set the environment variable `PYPROJ_GLOBAL_CONTEXT=ON` for faster projection calculations if thread safety is not a concern in your application.
When passing coordinate pairs to Cartopy functions, ensure they are in `(longitude, latitude)` order, not `(latitude, longitude)`.
Install Cartopy using conda (recommended, as it handles complex C/C++ dependencies like GEOS and PROJ more robustly) or pip: `conda install -c conda-forge cartopy` or `pip install cartopy`
Use Conda to install Cartopy and its dependencies: `conda install -c conda-forge cartopy`. If using pip on Linux, ensure `libproj-dev` and `proj-data` are installed via your system's package manager (e.g., `sudo apt-get install libproj-dev proj-data proj-bin`). For Windows, installing via a Conda distribution is strongly recommended.
Ensure `shapely` and `GEOS` are up-to-date and compatible with your Cartopy version, ideally by installing Cartopy via `conda-forge`: `conda install -c conda-forge cartopy`. If the issue persists with specific data, try simplifying or validating the input geometries using `shapely.geometry.Polygon.buffer(0)` or `shapely.geometry.Polygon.is_valid` to repair topological errors.
Always explicitly specify the `transform` argument in plotting functions (e.g., `ax.contourf`, `ax.plot`, `ax.imshow`) to indicate the coordinate system of your *data*. For example, if your data is in latitude/longitude, use `transform=ccrs.PlateCarree()`.
Install Cartopy using Conda, as it manages these complex binary dependencies reliably: `conda install -c conda-forge cartopy`. If forced to use `pip` on Windows, ensure all external dependencies (PROJ, GEOS, GDAL) are pre-installed correctly and their DLLs are discoverable in the system PATH or via `os.add_dll_directory()` if using Python 3.8+ before importing.