How to Resolve "ModuleNotFoundError: No module named pycocotools" in Python

When working with object detection models, particularly those trained on the COCO dataset, you will need the pycocotools library. If it's not installed, you will encounter the ModuleNotFoundError: No module named 'pycocotools'. This error occurs because pycocotools is not a standard package available on the Python Package Index (PyPI), so a simple pip install pycocotools will fail.

Instead, it must be installed directly from its source repository or through a community-maintained channel like conda-forge. This guide will walk you through the three primary methods for successfully installing pycocotools and resolving this error.

Understanding the Error: A Non-PyPI Package

The pycocotools library provides the official APIs for working with the COCO (Common Objects in Context) dataset. Unlike most Python packages, it is distributed as source code on GitHub and requires compilation (specifically, a C compiler and Cython) to be installed. This is why a direct pip install fails and why a more specific installation process is required.

Example of code causing the error:

from pycocotools.coco import COCO

Output:

Traceback (most recent call last):
  File "main.py", line 2, in <module>
    from pycocotools.coco import COCO
ModuleNotFoundError: No module named 'pycocotools'

Solution 1: Install from conda-forge (Easiest Method for Conda Users)

If you are using the Anaconda or Miniconda distribution, the easiest and most reliable way to install pycocotools is from the conda-forge channel. This method automatically handles the compilation and all necessary dependencies for you.

Solution:

conda install -c conda-forge pycocotools

This single command is usually sufficient for Conda users to get up and running without any issues.

Solution 2: Install a Pre-compiled Version with pip (Recommended for Pip Users)

For pip users, the simplest approach is to install a pre-compiled ("wheel") version from a third-party repository that has done the compilation work for you. This avoids the need to set up a C compiler on your own system.

Solution: a popular and well-maintained fork provides pre-compiled binaries for Windows, Linux, and macOS. You can install it directly from GitHub using pip.

pip install 'git+https://github.com/philferriere/cocoapi.git#subdirectory=PythonAPI'

After a successful installation, you will see a message like Successfully installed pycocotools-2.0.

Solution 3: Build from Source (Official Method)

This is the most advanced method and requires you to have the necessary build tools installed on your system.

Step 1: Install Prerequisites You need git, a C compiler (like gcc), and cython.

pip install cython

sudo apt-get install build-essential

xcode-select --install

Step 2: Clone the Repository and Build

git clone https://github.com/cocodataset/cocoapi.git

cd cocoapi/PythonAPI/

make install

Troubleshooting: When the Error Persists

If you have installed the package but still see the ModuleNotFoundError, it is almost certainly due to an environment mismatch.

• Multiple Python Versions: You may have installed pycocotools in one Python version but are running your script with another. Use python3 -m pip install ... to be explicit.
• Virtual Environment Not Activated: If you installed the package in a virtual environment, ensure that environment is activated before you run your script.
• IDE Configuration: Make sure your IDE (like VS Code or PyCharm) is configured to use the correct Python interpreter that has pycocotools installed.

Conclusion

For most users, the conda or pre-compiled pip methods are the fastest and most straightforward ways to resolve the ModuleNotFoundError: No module named 'pycocotools'.