Skip to main content

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

The ModuleNotFoundError: No module named 'mpl_toolkits.basemap' occurs when you try to import the Matplotlib Basemap Toolkit, but the basemap library is not installed in the Python environment your code is running in. Basemap is a third-party library and does not come bundled with Python or Matplotlib.

This guide will walk you through the primary solution of installing the package and then provide a systematic troubleshooting process for common environment-related issues that can cause this error even after a successful installation.

warning

Deprecation Notice: Consider Using cartopy

The Matplotlib Basemap Toolkit is officially deprecated and is no longer being actively developed. The developers now recommend using the more modern and powerful cartopy library for cartographic plotting in Python.

While this guide will help you fix the basemap installation, you should consider migrating to cartopy for new projects to ensure long-term support and access to new features.

Understanding the Error: A Missing Third-Party Package​

The mpl_toolkits directory is a "namespace package" that can be populated by external libraries. The basemap library, when installed, places its basemap module inside this namespace. The ModuleNotFoundError is Python's way of telling you that it looked for mpl_toolkits.basemap but couldn't find it because the basemap package itself is missing from your environment.

Example of code causing the error:

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

# This code will fail if basemap is not installed
map = Basemap()
map.drawcoastlines()
plt.show()

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from mpl_toolkits.basemap import Basemap
ModuleNotFoundError: No module named 'mpl_toolkits.basemap'

Solution 1: Install the basemap Package​

The most direct solution is to install the basemap library using a package manager like pip or conda.

Solution:

# Install using pip
pip install basemap

# If you use Python 3, you may need pip3
pip3 install basemap
note

Installation Commands for Different Environments

  • Explicit Python: python3 -m pip install basemap
  • Anaconda: conda install -c conda-forge basemap
  • Jupyter Notebook: !pip install basemap

After the installation completes, try running your Python script again. For most users, this will resolve the error.

Troubleshooting: When Installation Doesn't Fix the Error​

If you have installed the package but still see the ModuleNotFoundError, it is almost certainly due to an environment mismatch. This means your code is being executed by a different Python interpreter than the one where basemap was installed.

Problem: Multiple Python Versions Installed​

Your system might have several Python installations (e.g., one from the OS at /usr/bin/python3 and one from Homebrew at /opt/homebrew/bin/python3). The pip command you used might be linked to one version, while the python command is linked to another.

Solution: Be explicit. Use your Python interpreter to run pip as a module. This guarantees the package is installed for the correct version.

# Find the path of the Python you use to run your script
which python3
# Example output: /opt/homebrew/bin/python3

# Now, use that specific Python path to install the package
/opt/homebrew/bin/python3 -m pip install basemap

Problem: Virtual Environment is Not Activated​

If you installed basemap while a virtual environment was active, it is only available within that environment. If you try to run your script from a regular terminal session, it won't be able to find the package.

Solution: Always activate the correct virtual environment before running your script.

# Activate your virtual environment
source path/to/your/venv/bin/activate

# Your terminal prompt will now change, e.g., (venv) $
# Now you can run your script successfully
(venv) $ python your_map_script.py

Problem: IDE is Using the Wrong Python Interpreter​

IDEs like VS Code or PyCharm manage their own Python interpreter settings. The interpreter your IDE uses might be different from the one in your system's terminal.

Solution: VS Code

  1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
  2. Type and select "Python: Select Interpreter".
  3. Choose the interpreter that has basemap installed (it will often show the path, including the virtual environment name like ./venv/bin/python).

Solution: PyCharm PyCharm often creates a separate virtual environment for each project.

  1. Go to File > Settings (or PyCharm > Preferences on macOS).
  2. Navigate to Project: [your-project-name] > Python Interpreter.
  3. Click the + icon to install packages. Search for basemap and click "Install Package".

Conclusion​

Underlying ProblemHow to Fix
Package is not installedInstall it: pip install basemap or conda install -c conda-forge basemap.
Environment MismatchEnsure you are using the same Python interpreter to install the package and run your code.
Virtual EnvironmentMake sure your virtual environment is activated before running your script.
IDE ConfigurationSet the correct Python interpreter within your IDE's settings.

While these steps will resolve the ModuleNotFoundError, remember that Basemap is deprecated. For new projects, investing time in learning cartopy is the recommended long-term solution.

Table of Contents