Registry / ai-ml / pycocotools

pycocotools

JSON →
library2.0.11pypypi✓ verified 26d ago

Pycocotools provides the official APIs for the Microsoft COCO (Common Objects in Context) dataset. It facilitates loading, parsing, and visualizing COCO annotations, as well as evaluating object detection, segmentation, and keypoint detection results. The current version is 2.0.11, and it is actively maintained with bug fixes and packaging improvements over the original COCO API.

pip install pycocotools
INSTALL
IMPORT
SIG · PYCOCOTOOLS
P
pycocotools
ai-mlpythonv2.0.11
Install
4.4s avg
Import
340ms
Disk
94MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.344s · 90.5MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 4.4s · import 0.335s · 87MB
94MB installed
● package 94MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

COCO
from pycocotools.coco import COCO
COCOeval
from pycocotools.cocoeval import COCOeval
maskUtils
from pycocotools import mask as maskUtils

This quickstart demonstrates how to initialize the COCO API, load an annotation file, and retrieve basic information such as image and category IDs, and annotations for a specific image. It requires a downloaded COCO annotation JSON file.

import os from pycocotools.coco import COCO # NOTE: You need to download COCO annotations first. # For example, 'instances_val2017.json' can be found at: # http://images.cocodataset.org/annotations/annotations_trainval2017.zip # Placeholder for annotation file path. Replace with actual path. annFile = os.environ.get('COCO_ANN_FILE', 'path/to/instances_val2017.json') # Initialize COCO API for instance annotations try: coco = COCO(annFile) print(f"Successfully loaded COCO annotations from {annFile}") # Get all image IDs imgIds = coco.getImgIds() print(f"Total images: {len(imgIds)}") # Get category IDs catIds = coco.getCatIds(catNms=['person', 'dog', 'cat']) print(f"Categories found: {coco.loadCats(catIds)}") # Pick an image and display some info img = coco.loadImgs(imgIds[0])[0] print(f"First image info: {img}") # Get annotations for the image annIds = coco.getAnnIds(imgIds=img['id'], catIds=catIds, iscrowd=None) anns = coco.loadAnns(annIds) print(f"Annotations for image {img['id']}: {len(anns)} found") except Exception as e: print(f"Error loading COCO annotations or processing: {e}") print("Please ensure the annotation file path is correct and accessible.")
Debug
Known issues
gotchaWindows users frequently encounter compilation errors requiring 'Microsoft Visual C++ Build Tools'. These tools must be installed (specifically 'Desktop development with C++' workload) before `pip install pycocotools` can succeed.
fix
Install 'Desktop development with C++' workload from Visual Studio Build Tools. For Python 3.9+, ensure compatibility with the installed C++ compiler version.
affects: All versions on Windows
breakingThe `useSegm` parameter in `COCOeval` has been deprecated and replaced by the `iouType` parameter. Attempting to use `useSegm` will likely result in an error or unexpected behavior.
fix
Replace `E.params.useSegm = True/False` with `E.params.iouType = 'segm'` or `E.params.iouType = 'bbox'` respectively.
affects: 2.0.0 and later
gotchaC-extension compilation can fail if `numpy` or `cython` are not correctly installed or if there are environment-specific compiler issues. Although `pycocotools` lists them as dependencies, explicit pre-installation can sometimes resolve issues.
fix
Ensure `pip install cython numpy` is run before `pip install pycocotools`. For persistent issues, verify your C/C++ compiler setup (e.g., GCC on Linux, Visual C++ Build Tools on Windows).
affects: All versions, especially in complex environments or non-standard OS setups.
Errors
Common errors & fixes
Microsoft Visual C++ 14.0 or greater is required. / Failed building wheel for pycocotools
Pycocotools includes C extensions that need to be compiled during installation, and this error indicates that a compatible C++ compiler (like Microsoft Visual C++ Build Tools) is either missing or not correctly configured on Windows systems.
fix
Install 'Build Tools for Visual Studio' from Microsoft's website, ensuring to select the 'Desktop development with C++' workload. Alternatively, for Windows, `pip install pycocotools-windows` often resolves this by providing pre-built wheels.
ModuleNotFoundError: No module named 'pycocotools._mask'
This error occurs when the `_mask` C extension module, which is a critical part of `pycocotools` for efficient mask operations, was not successfully compiled or installed, or Python cannot find it. This is often a consequence of underlying C++ compiler issues or an incomplete installation.
fix
Ensure C++ build tools are correctly installed and configured. If on Windows, `pip install pycocotools-windows` is recommended. For manual installation from source, ensure Cython is installed (`pip install cython`), then navigate to the `PythonAPI` directory of the cloned `cocoapi` repository and run `python setup.py build_ext --inplace` followed by `python setup.py install`.
ImportError: No module named 'pycocotools'
This is a general Python import error, indicating that the `pycocotools` package is not found by the Python interpreter in the current environment. This typically means the package was not installed, was installed in a different virtual environment, or its installation was corrupted.
fix
Install the package using `pip install pycocotools`. If you are on Windows and encountering persistent issues, try `pip install pycocotools-windows`. Ensure you are installing it into the correct Python environment you intend to use.
AttributeError: module 'pycocotools' has no attribute 'mask'
This error arises when trying to access `mask` as a direct attribute of the `pycocotools` module without explicitly importing the `mask` submodule. Importing `pycocotools` alone does not automatically make its submodules available as top-level attributes.
fix
Explicitly import the `mask` submodule from `pycocotools` using `import pycocotools.mask` or `from pycocotools import mask as coco_mask`.
Upgrade
Version history
2.0.11latest on PyPI · released Dec 15, 2025
Audit
Dependencies
numpyrequiredFundamental for numerical operations and array handling.
cythonrequiredRequired to compile C extensions for mask operations, often needs explicit pre-installation.
matplotliboptionalUsed for visualization functions (e.g., `showAnns`), but not strictly required for core API usage.
scikit-imageoptionalSometimes used in examples or for image loading (e.g., `skimage.io`).
Agent activity
47 hits · last 30 days
node
40
OpenAI (training)
1
Resources
pycocotools — pip install pycocotools · libregistry