Matplotlib Basemap Toolkit

Common errors

• OSError: Could not find libproj.so.0 or libproj.dylib

  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.
  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.

• ImportError: No module named 'mpl_toolkits.basemap'

  cause The Basemap library is not installed in your active Python environment or was installed incorrectly.
  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"`.

• TypeError: 'Basemap' object is not callable

  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.
  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.

• AttributeError: module 'matplotlib.pyplot' has no attribute 'figure'

  cause Incompatibility between the installed Basemap and Matplotlib versions. Basemap 2.0.0 specifically requires Matplotlib >= 3.5.0.
  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.

Warnings

• breaking 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.
  Fix: Migrate new code to `cartopy` or `geopandas`. For existing projects, consider a migration strategy.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Stick to the Matplotlib version range specified in Basemap's dependencies. If using Basemap, avoid aggressively upgrading Matplotlib unless compatibility is explicitly verified.

Install

• pip install basemap Basic pip install (requires system dependencies)
• conda install -c conda-forge basemap Recommended conda install (handles dependencies)

Imports

• Basemap

  from mpl_toolkits.basemap import Basemap

Quickstart

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.

import matplotlib.pyplot as plt
from mpl_toolkits.basemap import Basemap

# Create a new figure
fig = plt.figure(figsize=(8, 6))

# Create a Basemap instance for a global cylindrical projection
m = Basemap(projection='mill', llcrnrlat=-90, urcrnrlat=90,
            llcrnrlon=-180, urcrnrlon=180, resolution='l')

# Draw coastlines, countries, parallels, and meridians
m.drawcoastlines()
m.drawcountries()
m.drawparallels(range(-90, 91, 30))
m.drawmeridians(range(-180, 181, 60))

plt.title("Simple Basemap Example (Deprecated)")

# Save the plot instead of showing it for script execution
plt.savefig("basemap_example.png")
print("Basemap example plot saved to basemap_example.png")