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.

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

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:

pip install basemap

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

which python3

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

source path/to/your/venv/bin/activate

(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

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.