{"id":3919,"library":"cartopy","title":"Cartopy","description":"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.","status":"active","version":"0.25.0","language":"en","source_language":"en","source_url":"https://github.com/SciTools/cartopy","tags":["mapping","gis","geospatial","matplotlib","visualization","cartography","projections"],"install":[{"cmd":"pip install cartopy","lang":"bash","label":"PyPI (pip)"},{"cmd":"conda install -c conda-forge cartopy","lang":"bash","label":"Conda (Recommended for dependency handling)"}],"dependencies":[{"reason":"Required Python version.","package":"python","version":">=3.10"},{"reason":"Essential for any graphical output.","package":"matplotlib","version":">=3.6"},{"reason":"Core dependency for scientific computing.","package":"numpy","version":">=1.6"},{"reason":"Python interface to PROJ (cartographic projections). Required for transformations.","package":"pyproj","version":">=3.3.1"},{"reason":"Python package for manipulation and analysis of planar geometric objects. Essential for features.","package":"shapely","version":">=2.0"},{"reason":"Pure Python read/write support for ESRI Shapefile format.","package":"pyshp","version":">=2.3"},{"reason":"Utilities for version handling.","package":"packaging"},{"reason":"Underlying C++ library for geometric operations (often installed with shapely).","package":"GEOS","optional":true},{"reason":"Underlying C library for cartographic projections (often installed with pyproj).","package":"PROJ","optional":true},{"reason":"Translator library for raster/vector geospatial data formats.","package":"gdal","optional":true},{"reason":"Image processing library, often used for background images.","package":"Pillow","optional":true},{"reason":"Fast kd-tree implementation for image warping.","package":"pykdtree","optional":true},{"reason":"For client programming with Open Geospatial Consortium (OGC) web services.","package":"owslib","optional":true}],"imports":[{"note":"Common alias for Coordinate Reference Systems.","symbol":"crs","correct":"import cartopy.crs as ccrs"},{"note":"Common alias for adding geographical features like coastlines, borders.","symbol":"feature","correct":"import cartopy.feature as cfeature"},{"note":"Specifically imports the GeoAxes class, often used for type hinting or specific Matplotlib manipulations.","symbol":"GeoAxes","correct":"from cartopy.mpl.geoaxes import GeoAxes"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport cartopy.crs as ccrs\nimport cartopy.feature as cfeature\n\nfig = plt.figure(figsize=(10, 8))\nax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())\n\nax.set_global()\n\n# Add basic features\nax.add_feature(cfeature.LAND)\nax.add_feature(cfeature.OCEAN)\nax.add_feature(cfeature.COASTLINE)\nax.add_feature(cfeature.BORDERS, linestyle=':')\nax.add_feature(cfeature.LAKES, alpha=0.5)\nax.add_feature(cfeature.RIVERS)\n\nplt.title('Basic Cartopy Map with Plate Carree Projection')\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer.","message":"Python 2 support was removed in Cartopy v0.19. Users on older Python versions must upgrade to Python 3.7+ (v0.20) or 3.10+ (v0.25).","severity":"breaking","affected_versions":">=0.19"},{"fix":"Replace calls like `ax.natural_earth_shp('110m', 'coastline')` with `ax.add_feature(cfeature.COASTLINE)`. Check `cartopy.feature` for other available features.","message":"The `Axes.natural_earth_shp()` method has been removed. Use `Axes.add_feature()` along with classes from the `cartopy.feature` module instead.","severity":"breaking","affected_versions":">=0.16"},{"fix":"Use the replacement attributes: `Gridliner.top_labels`, `bottom_labels`, `left_labels`, or `right_labels`.","message":"Gridliner label control attributes like `Gridliner.xlabels_top`, `xlabels_bottom`, `ylabels_left`, and `ylabels_right` are removed. They were deprecated in v0.18 and removed in v0.23.","severity":"deprecated","affected_versions":">=0.23"},{"fix":"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.","message":"The `cartopy.mpl.clip_path` module is deprecated without replacement, and `path_to_geos`/`geos_to_path` are deprecated in favor of `path_to_shapely`/`shapely_to_path`. This affects low-level path manipulation.","severity":"breaking","affected_versions":">=0.25"},{"fix":"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+.","message":"Installing Cartopy via `pip` can be challenging due to its complex external (GEOS, PROJ) and Python (Shapely, pyproj) dependencies, especially on Windows or when pre-built wheels are unavailable. Conda is often recommended for a smoother installation.","severity":"gotcha","affected_versions":"All"},{"fix":"Set the environment variable `PYPROJ_GLOBAL_CONTEXT=ON` for faster projection calculations if thread safety is not a concern in your application.","message":"From v0.20, Cartopy uses `pyproj` for transformations, which can sometimes be slower. An environment variable can improve performance.","severity":"gotcha","affected_versions":">=0.20"},{"fix":"When passing coordinate pairs to Cartopy functions, ensure they are in `(longitude, latitude)` order, not `(latitude, longitude)`.","message":"Internal function calls in Cartopy (e.g., for geometries) now prefer `(longitude, latitude)` ordering for consistency.","severity":"gotcha","affected_versions":">=0.25"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}