One error that you might encounter when working with Python is:
ModuleNotFoundError: No module named 'mpl_toolkits.basemap'
This error occurs when Python can’t find the Basemap package, which contains the mpl_toolkits.basemap module in your current Python environment.
This tutorial shows examples that cause this error and how to fix it.
How to reproduce the error
Suppose you want to use the mpl_toolkits.basemap module to create a plot on a map.
You import the mpl_toolkits.basemap module and write the following code:
from mpl_toolkits.basemap import Basemap
import matplotlib.pyplot as plt
map = Basemap()
map.drawcoastlines()
plt.show()
plt.savefig('result.png')
But you get the following error when running the code:
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'
This error occurs because Python can’t find the Basemap package in the current environment. The Basemap package is not a built-in Python package, so you need to install it before using it.
To see if you have the Basemap package installed, you can run the pip show basemap command from the terminal as follows:
$ pip3 show basemap
WARNING: Package(s) not found: basemap
If you get the warning shown above, then you need to install the Basemap package.
How to fix this error
To resolve this error, you need to install the Basemap package using pip as shown below:
pip install basemap
# For pip3:
pip3 install basemap
Once the module is installed, you should be able to run the code that needs the mpl_toolkits.basemap module without receiving the error.
Install commands for other environments
The install command might differ depending on what environment you used to run the Python code.
Here’s a list of common install commands in popular Python environments to install the Basemap package:
# if you don't have pip in your PATH:
python -m pip install basemap
# or:
python3 -m pip install basemap
# Windows
py -m pip install basemap
# Anaconda
conda install basemap
# or:
conda install -c conda-forge basemap
# Jupyter Notebook
!pip install basemap
!pip install basemap-data
Once the module is installed, you should be able to run the code without receiving this error.
Other common causes for this error
If you still see the error even after installing the module, it means that the Basemap package can’t be found in your Python environment.
There are several reasons why this error can happen:
- You may have multiple versions of Python installed on your system, and you are using a different version of Python than the one where Basemap is installed.
- You might have Basemap installed in a virtual environment, and you are not activating the virtual environment before running your code.
- Your IDE uses a different version of Python from the one that has Basemap
- The package is not installed in PyCharm
Let’s see how to fix these errors in practice.
1. You have multiple versions of Python
If you have multiple versions of Python installed on your system, you need to make sure that you are using the specific version where the Basemap module is available.
You can test this by running the which -a python or which -a python3 command from the terminal:
$ which -a python3
/opt/homebrew/bin/python3
/usr/bin/python3
In the example above, there are two versions of Python installed on /opt/homebrew/bin/python3 and /usr/bin/python3.
Suppose you run the following steps in your project:
- Install Basemap with
pipusing/usr/bin/Python version - Install Python using Homebrew, you have Python in
/opt/homebrew/ - Then you run code that uses the Basemap package
The steps above will cause the error because Basemap is installed in /usr/bin/, and your code is probably executed using Python from /opt/homebrew/ path.
To solve this error, you need to run the pip install basemap command again so that Basemap is installed and accessible by the active Python version.
2. Python virtual environment is active
Another scenario that could cause this error is you may have Basemap installed in a virtual environment.
Python venv package allows you to create a virtual environment where you can install different versions of packages required by your project.
If you are installing Basemap inside a virtual environment, then the module won’t be accessible outside of that environment.
You can see if a virtual environment is active or not by looking at your prompt in the terminal.
When a virtual environment is active, the name of that environment will be shown inside parentheses as shown below:
In the picture above, the name of the virtual environment (demoenv) appears, indicating that the virtual environment is currently active.
If you run pip install while the virtual environment is active, then the package is installed only for that environment
Likewise, any package installed outside of that virtual environment won’t be accessible from the virtual environment. The solution is to run the pip install command on the environment you want to use.
If you want to install Basemap globally, then turn off the virtual environment by running the deactivate command before running the pip install command.
3. IDE using a different Python version
Finally, the IDE from where you run your Python code may use a different Python version when you have multiple versions installed.
For example, you can check the Python interpreter used in VSCode by opening the command palette (CTRL + Shift + P for Windows and ⌘ + Shift + P for Mac) then run the Python: Select Interpreter command.
You should see all available Python versions listed as follows:
You need to use the same version where you installed Basemap so that the module can be found when you run the code from VSCode.
Once done, you should be able to import Basemap into your code.
4. You see this error in PyCharm
If you’re using PyCharm as your IDE, then this error might occur because the package is not installed in the Python interpreter used by PyCharm.
This is because PyCharm creates a new virtual environment for each project you create using the IDE. When you run the code, an error is shown as follows:
To resolve this error, you can right-click on the squiggly red lines to open the context menu, then click on Show Context Actions > Install package Basemap.
The package should be installed, and you can run the code without receiving any error.
For more information, you can see the guide to install and uninstall packages in PyCharm.
Conclusion
In summary, the ModuleNotFoundError: No module named 'mpl_toolkits.basemap' error occurs when the Basemap package is not available in your Python environment. To fix this error, you need to install Basemap using pip.
If you already have the module installed, make sure you are using the correct version of Python, check if the virtual environment is active if you have one, and check for the Python version used by your IDE.
By following these steps, you should be able to import the mpl_toolkits.basemap module in your code successfully.
I hope this tutorial is helpful. Happy coding! 👍