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.

Important: Basemap Is Deprecated

Basemap has been officially deprecated by the matplotlib project. The maintainers recommend migrating to Cartopy for all new projects. Basemap still works but no longer receives active development or bug fixes. We cover Basemap installation below for legacy projects, but also show the Cartopy alternative at the end of this guide.

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:

# Install the main basemap package
pip install git+https://github.com/matplotlib/basemap.git

# Install the map data (coastlines, borders, etc.)
pip install basemap-data

# Optional: Install high-resolution map data
pip install basemap-data-hires

Build Requirements

Installing from GitHub requires a C compiler because Basemap includes C extensions that must be compiled. On different platforms:

• Ubuntu/Debian: sudo apt-get install build-essential libgeos-dev
• macOS: xcode-select --install and brew install geos
• Windows: Install Microsoft Visual C++ Build Tools

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!")

    # Create a simple map
    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:

# Verify which Python is being used
python -c "import sys; print(sys.executable)"

# List installed packages to confirm basemap is there
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:

# Ubuntu/Debian
sudo apt-get install libgeos-dev

# macOS
brew install geos

# Then reinstall basemap
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:

# Create and activate a virtual environment
python -m venv mapenv
source mapenv/bin/activate  # Windows: mapenv\Scripts\activate

# Install basemap inside the environment
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:

# Using conda (recommended)
conda install -c conda-forge cartopy

# Using pip
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

Feature	Basemap	Cartopy
Status	Deprecated	Actively maintained
Python 3.12+ support	Limited/None	✅ Yes
Installation difficulty	Moderate to difficult	Easy with conda
Map projections	Good selection	Extensive selection
Integration with matplotlib	Extension	Native subplot integration
Shapefile support	Basic	Advanced with shapely
Performance	Adequate	Better for large datasets

Migration Guide

If you're migrating from Basemap to Cartopy, the key changes are:

• Basemap(projection='merc') → ccrs.Mercator()
• m.drawcoastlines() → ax.add_feature(cfeature.COASTLINE)
• m.drawcountries() → ax.add_feature(cfeature.BORDERS)
• Data plotting uses standard matplotlib methods with a transform parameter

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.