Skip to main content

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:

# This import will fail if pycocotools is not installed
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.

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.

# Note the quotes for Zsh users to prevent globbing
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.

# Install Cython
pip install cython

# On Debian/Ubuntu, install a compiler
sudo apt-get install build-essential

# On macOS, install Xcode command line tools
xcode-select --install

Step 2: Clone the Repository and Build

# Clone the official cocoapi repository
git clone https://github.com/cocodataset/cocoapi.git

# Navigate into the Python API directory
cd cocoapi/PythonAPI/

# Run the build and install command
make install
warning

Common Build Error: On some systems, the make install command may fail with an error like error: command 'gcc' failed with exit status 1 because the Makefile defaults to using python instead of python3.

To fix this, open the Makefile in a text editor and change the two occurrences of python to python3:

# Change this:
# python setup.py build_ext --inplace
# To this:
python3 setup.py build_ext --inplace

# And this:
# python setup.py build_ext install
# To this:
python3 setup.py build_ext install

After saving the change, run make install again.

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​

Your Environment / GoalRecommended Solution
CondaInstall from conda-forge: conda install -c conda-forge pycocotools
Pip (Standard)Install a pre-compiled version: pip install 'git+...'
Advanced / OfficialBuild from the source repository after installing a C compiler and Cython.

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

Table of Contents