{"id":9545,"library":"basemap","title":"Matplotlib Basemap Toolkit","description":"Basemap is a deprecated Python library for plotting 2D data on map projections with Matplotlib. While it enabled various map projections, coastlines, and geopolitical boundaries, it is no longer actively developed and is officially superseded by Cartopy. The current version is 2.0.0.","status":"deprecated","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/matplotlib/basemap.git","tags":["mapping","plotting","geospatial","matplotlib","deprecated"],"install":[{"cmd":"pip install basemap","lang":"bash","label":"Basic pip install (requires system dependencies)"},{"cmd":"conda install -c conda-forge basemap","lang":"bash","label":"Recommended conda install (handles dependencies)"}],"dependencies":[{"reason":"Required for all plotting. Basemap 2.0.0 requires Matplotlib >= 3.5.0.","package":"matplotlib"},{"reason":"Core numerical dependency. Basemap 2.0.0 requires Numpy >= 1.21.0.","package":"numpy"},{"reason":"Used for various scientific computations. Basemap 2.0.0 requires Scipy >= 1.7.0.","package":"scipy"},{"reason":"System-level library required for map projections. Basemap 2.0.0 specifically requires PROJ 6+ API.","package":"proj","optional":false},{"reason":"System-level library required for geometric operations.","package":"geos","optional":false}],"imports":[{"symbol":"Basemap","correct":"from mpl_toolkits.basemap import Basemap"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nfrom mpl_toolkits.basemap import Basemap\n\n# Create a new figure\nfig = plt.figure(figsize=(8, 6))\n\n# Create a Basemap instance for a global cylindrical projection\nm = Basemap(projection='mill', llcrnrlat=-90, urcrnrlat=90,\n            llcrnrlon=-180, urcrnrlon=180, resolution='l')\n\n# Draw coastlines, countries, parallels, and meridians\nm.drawcoastlines()\nm.drawcountries()\nm.drawparallels(range(-90, 91, 30))\nm.drawmeridians(range(-180, 181, 60))\n\nplt.title(\"Simple Basemap Example (Deprecated)\")\n\n# Save the plot instead of showing it for script execution\nplt.savefig(\"basemap_example.png\")\nprint(\"Basemap example plot saved to basemap_example.png\")","lang":"python","description":"This quickstart demonstrates how to initialize a Basemap instance with a 'mill' (Miller cylindrical) projection, draw basic map features like coastlines and meridians, and save the output to a file. Remember that Basemap is deprecated."},"warnings":[{"fix":"Migrate new code to `cartopy` or `geopandas`. For existing projects, consider a migration strategy.","message":"Basemap is officially deprecated. For new projects, use Cartopy (or other modern geospatial libraries) instead. It is no longer actively maintained or developed, and support may cease completely.","severity":"breaking","affected_versions":"All versions, officially stated in the 2.0.0 release notes and GitHub README."},{"fix":"Ensure PROJ 6+ (e.g., `libproj.so.19` or `proj.dll` for PROJ 9+) and GEOS are installed on your system. Using `conda install -c conda-forge basemap` is often the most reliable way as it handles these dependencies.","message":"Basemap 2.0.0 requires PROJ 6+ and GEOS as system-level dependencies. PROJ 6 introduced a new API, which required significant changes in Basemap and frequently causes installation or runtime failures if these libraries are not present or correctly configured.","severity":"breaking","affected_versions":"2.0.0 and later."},{"fix":"Experiment with `figsize` in `plt.figure()`, and specific projection parameters like `lon_0`, `lat_0`, `width`, `height`, and `resolution` in the `Basemap` constructor. Consult Basemap examples for appropriate parameters for different projections and regions.","message":"Basemap plots can appear distorted or incorrect if the Matplotlib figure's aspect ratio or the chosen map projection parameters are not carefully configured for the specific geographical region being plotted.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Stick to the Matplotlib version range specified in Basemap's dependencies. If using Basemap, avoid aggressively upgrading Matplotlib unless compatibility is explicitly verified.","message":"Basemap relies heavily on Matplotlib. Incompatibility with newer Matplotlib versions (especially those significantly beyond 3.5.0, which Basemap 2.0.0 specifies as `>=3.5.0`) can lead to unexpected rendering issues or errors.","severity":"gotcha","affected_versions":"All versions, particularly with rapidly evolving Matplotlib versions."}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install PROJ at the system level: `sudo apt-get install libproj-dev proj-data` (Ubuntu/Debian) or `brew install proj` (macOS). Alternatively, use `conda install -c conda-forge basemap` which bundles these dependencies.","cause":"The PROJ C library (or its Windows equivalent .dll) is not installed on your system or is not found in your environment's PATH. Basemap requires it for map projections.","error":"OSError: Could not find libproj.so.0 or libproj.dylib"},{"fix":"`pip install basemap` or, more reliably for its C-level dependencies, `conda install -c conda-forge basemap`. Verify installation with `python -c \"import mpl_toolkits.basemap\"`.","cause":"The Basemap library is not installed in your active Python environment or was installed incorrectly.","error":"ImportError: No module named 'mpl_toolkits.basemap'"},{"fix":"Ensure you are calling methods on the `Basemap` instance (e.g., `m.plot`, `m.scatter`, or `m(lon, lat, inverse=False)`) and not treating the instance `m` itself as a function for coordinate transformation.","cause":"This error occurs when you try to use an instance of the `Basemap` class as if it were a function (e.g., `m(lon, lat)` without `inverse=False`), instead of calling its specific methods.","error":"TypeError: 'Basemap' object is not callable"},{"fix":"Downgrade or upgrade Matplotlib to a compatible version. For example, `pip install 'matplotlib>=3.5.0,<3.7.0'` to match Basemap 2.0.0's requirements, or check the Basemap documentation for the latest compatibility.","cause":"Incompatibility between the installed Basemap and Matplotlib versions. Basemap 2.0.0 specifically requires Matplotlib >= 3.5.0.","error":"AttributeError: module 'matplotlib.pyplot' has no attribute 'figure'"}]}