How to Resolve "No module named mpl_toolkits.basemap" in Python

When working with geographic data and trying to plot maps in Python, you may encounter the error ModuleNotFoundError: No module named 'mpl_toolkits.basemap'. This happens because the Basemap toolkit is not included with standard matplotlib installations and requires separate installation, which can be trickier than most Python packages.

In this guide, we'll walk through what Basemap is, why this error occurs, the correct installation methods, and also discuss modern alternatives you should consider.

What Is Basemap?

Basemap is an extension to matplotlib that adds the ability to plot data on geographic map projections. It can draw coastlines, countries, rivers, and various map projections, making it useful for geospatial data visualization.

Reproducing the Error

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

m = Basemap(projection='merc', llcrnrlat=-60, urcrnrlat=85,
            llcrnrlon=-180, urcrnrlon=180, resolution='c')
m.drawcoastlines()
plt.show()

Output:

ModuleNotFoundError: No module named 'mpl_toolkits.basemap'

The error occurs because basemap is not bundled with matplotlib and must be installed separately. Additionally, Basemap is not available on PyPI via a simple pip install basemap, which adds to the confusion.

How to Install Basemap

Prerequisites

Before installing Basemap, ensure you have the required dependencies:

pip install numpy matplotlib pyproj Pillow

Verify your Python version: Basemap works with Python 3.6 through 3.11 (compatibility with newer Python versions may be limited due to its deprecated status):

python --version
pip --version

Method 1: Install Using Conda (Recommended)

The easiest and most reliable way to install Basemap is through conda:

conda install -c conda-forge basemap basemap-data-hires

This installs Basemap along with high-resolution map data and handles all dependencies automatically.

If you only need low-resolution maps:

conda install -c conda-forge basemap

Method 2: Install Using pip from GitHub

If you're not using conda, you can install directly from the GitHub repository:

pip install git+https://github.com/matplotlib/basemap.git

pip install basemap-data

pip install basemap-data-hires

Method 3: Install Using Pre-built Wheels (Windows)

On Windows, compiling from source can be difficult. You can use pre-built wheels from Christoph Gohlke's repository (if available for your Python version):

pip install basemap-1.3.6-cp310-cp310-win_amd64.whl

Verifying the Installation

After installation, run this verification script:

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

    print("✅ Basemap imported successfully!")

    fig, ax = plt.subplots(figsize=(10, 6))
    m = Basemap(
        projection='robin',  # Robinson projection
        lon_0=0,
        resolution='c',
        ax=ax
    )
    m.drawcoastlines(linewidth=0.5)
    m.drawcountries(linewidth=0.5)
    m.fillcontinents(color='lightgreen', lake_color='lightblue')
    m.drawmapboundary(fill_color='lightblue')
    plt.title("Basemap Test: World Map")
    plt.show()
    print("✅ Map rendered successfully!")

except ModuleNotFoundError as e:
    print(f"❌ Import failed: {e}")
except Exception as e:
    print(f"❌ Error: {e}")

If a world map appears, Basemap is working correctly.

Troubleshooting

Issue: Installation Succeeds but Import Still Fails

Check that you're in the correct environment:

python -c "import sys; print(sys.executable)"

pip list | grep -i basemap

If basemap doesn't appear in the list, you may have installed it in a different Python environment.

Issue: libgeos Not Found

OSError: Could not find library geos_c or load any of its variants

Fix: Install the GEOS library:

sudo apt-get install libgeos-dev

brew install geos

pip install git+https://github.com/matplotlib/basemap.git

Issue: Compilation Errors on Windows

If you see errors about missing cl.exe or compilation failures on Windows, install the build tools:

1. Download Microsoft Visual C++ Build Tools.
2. Select "Desktop development with C++" during installation.
3. Restart your terminal and retry the installation.

Issue: Virtual Environment Not Activated

If you installed basemap globally but are running your script in a virtual environment (or vice versa), the module won't be found:

python -m venv mapenv
source mapenv/bin/activate  # Windows: mapenv\Scripts\activate

pip install numpy matplotlib pyproj Pillow
pip install git+https://github.com/matplotlib/basemap.git
pip install basemap-data

Recommended Alternative: Use Cartopy Instead

Since Basemap is deprecated, Cartopy is the recommended replacement for all new geospatial visualization projects. It's actively maintained, supports modern Python versions, and integrates cleanly with matplotlib.

Install Cartopy:

conda install -c conda-forge cartopy

pip install cartopy

Equivalent map with Cartopy:

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
import cartopy.feature as cfeature

fig, ax = plt.subplots(
    figsize=(10, 6),
    subplot_kw={'projection': ccrs.Robinson()}
)

ax.add_feature(cfeature.LAND, facecolor='lightgreen')
ax.add_feature(cfeature.OCEAN, facecolor='lightblue')
ax.add_feature(cfeature.COASTLINE, linewidth=0.5)
ax.add_feature(cfeature.BORDERS, linewidth=0.5, linestyle=':')
ax.set_global()
ax.set_title("Cartopy: World Map")
plt.show()

Basemap vs. Cartopy Comparison

Conclusion

The ModuleNotFoundError: No module named 'mpl_toolkits.basemap' error occurs because Basemap is not included with matplotlib and must be installed separately.

The easiest installation method is conda install -c conda-forge basemap. If using pip, install from the GitHub repository along with the basemap-data package, and ensure you have the GEOS C library installed on your system. However, since Basemap is officially deprecated, consider migrating to Cartopy for new projects: it's actively maintained, easier to install, and better supported across modern Python versions.