{"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":"python","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,"search_vec":"'0.25.0':41 'activ':45 'build':15 'cadenc':47 'cartograph':13 'cartographi':62 'cartopi':1,2 'current':38 'data':10,33 'definit':24 'design':7 'frequent':48 'geospati':9,55,59 'gis':58 'handl':34 'librari':36,56 'maintain':43 'map':28,57 'matplotlib':17,60 'modern':52 'object':21 'object-ori':20 'orient':22 'packag':6 'power':31 'process':11 'project':23,29,63 'provid':19 'python':5,53 'releas':46 'support':51 'transform':25 'updat':49 'various':27 'vector':32 'version':40 'visual':14,61","created_at":"2026-04-12T03:33:15.670118+00:00","updated_at":"2026-04-16T01:26:53.624527+00:00","problems":[{"fix":"Install Cartopy using conda (recommended, as it handles complex C/C++ dependencies like GEOS and PROJ more robustly) or pip:\n`conda install -c conda-forge cartopy`\nor\n`pip install cartopy`","cause":"The `cartopy` package is not installed in the active Python environment, or the environment where it was installed is not the one currently being used.","error":"ModuleNotFoundError: No module named 'cartopy'"},{"fix":"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.","cause":"Cartopy relies on external C/C++ libraries like PROJ. This error indicates that the PROJ library is either missing, an incompatible version, or its location cannot be found during Cartopy's installation or import, often when installing via `pip` without pre-installed system dependencies.","error":"UserWarning: Unable to determine Proj version. Ensure you have X.Y.Z or later installed, or installation may fail. Proj version 0.0.0 is installed, but cartopy requires at least version X.Y.Z."},{"fix":"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.","cause":"This error occurs when geometric operations (e.g., drawing features, contours) encounter invalid or self-intersecting geometries within the underlying `shapely` and `GEOS` libraries that Cartopy uses. It can be triggered by malformed input data or conflicts with specific versions of dependencies like `shapely` or `GEOS`.","error":"GEOSException: The operation 'GEOSIntersection_r' could not be performed. Likely cause is invalidity of the geometry"},{"fix":"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()`.","cause":"When plotting data on a Cartopy `GeoAxes`, the `transform` argument is often omitted or set incorrectly, causing Cartopy to assume the data's coordinate system matches the map's projection, leading to misplaced or distorted data.","error":"Data plotting incorrectly on Cartopy map (wrong location/projection)"},{"fix":"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.","cause":"This error, common on Windows, indicates that a dynamic-link library (DLL) dependency for Cartopy (or one of its underlying libraries like PROJ or GEOS) cannot be found by Python. This is often due to changes in Python's DLL loading behavior (especially Python 3.8+) or issues with how these binary dependencies are installed.","error":"ImportError: DLL load failed while importing _xxx: The specified module could not be found"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.25.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://scitools.org.uk/cartopy/","github":"https://github.com/SciTools/cartopy","docs":"https://scitools.org.uk/cartopy/docs/latest/","changelog":null,"pypi":"https://pypi.org/project/cartopy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}