Install & Compatibility
Where this runs
tested against v1.7.2 · 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
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 8.0s · import 0.351s · 87MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
COCO
✓ from faster_coco_eval import COCO
Main class for loading COCO annotations.
COCOeval
✓ from faster_coco_eval import COCOeval
Standard COCO evaluation class (faster implementation).
COCOeval_faster
✓ from faster_coco_eval import COCOeval_faster
Explicitly use the faster evaluation class.
init_as_pycocotools
✓ import faster_coco_eval
faster_coco_eval.init_as_pycocotools()
Activates faster-coco-eval as a drop-in replacement for pycocotools, allowing existing pycocotools import statements to use the faster backend.
Curves
✓ from faster_coco_eval.extra import Curves
Utility for plotting precision-recall and other metric curves.
This quickstart demonstrates two ways to use `faster-coco-eval`. The first method utilizes `faster_coco_eval.init_as_pycocotools()` to replace `pycocotools` imports with the faster implementation, allowing for seamless integration into existing code. The second method shows direct usage of `faster_coco_eval`'s `COCO` and `COCOeval_faster` classes. You will need COCO-formatted ground truth annotation and prediction JSON files.
import os
import faster_coco_eval
# Option 1: Use faster_coco_eval as a drop-in replacement for pycocotools
faster_coco_eval.init_as_pycocotools()
from pycocotools.coco import COCO
from pycocotools.cocoeval import COCOeval
# Create dummy COCO JSON files (replace with your actual paths)
# Example structure based on common COCO format expectations
# In a real scenario, you'd load these from actual files.
anno_json_path = "annotations_val2017.json" # Path to your ground truth annotations
pred_json_path = "results_predictions.json" # Path to your model's predictions
# Simulate creating dummy JSON files for demonstration
# In practice, these files would already exist.
if not os.path.exists(anno_json_path):
with open(anno_json_path, 'w') as f:
f.write('{"images": [], "annotations": [], "categories": []}')
if not os.path.exists(pred_json_path):
with open(pred_json_path, 'w') as f:
f.write('[]')
# Load annotations and predictions
# For a real run, ensure your JSON files contain actual data.
try:
coco_gt = COCO(anno_json_path)
coco_dt = coco_gt.loadRes(pred_json_path)
# Evaluate bounding boxes
coco_eval = COCOeval(coco_gt, coco_dt, "bbox")
coco_eval.evaluate()
coco_eval.accumulate()
coco_eval.summarize()
print("COCO evaluation (bbox) summarized.")
# Option 2: Directly use faster_coco_eval classes (alternative to init_as_pycocotools)
from faster_coco_eval import COCO as FasterCOCO, COCOeval_faster
# Load annotations and predictions
coco_gt_f = FasterCOCO(anno_json_path)
coco_dt_f = coco_gt_f.loadRes(pred_json_path)
# Evaluate segmentation masks
coco_eval_f = COCOeval_faster(coco_gt_f, coco_dt_f, "segm")
coco_eval_f.evaluate()
coco_eval_f.accumulate()
coco_eval_f.summarize()
print("Faster COCO evaluation (segm) summarized.")
except Exception as e:
print(f"An error occurred during COCO evaluation: {e}")
print("Please ensure your annotation and prediction JSON files are valid and contain data.")
# Clean up dummy files
os.remove(anno_json_path)
os.remove(pred_json_path)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'faster_coco_eval'
The 'faster-coco-eval' library is not installed in the current Python environment or the environment variables are not correctly set up.
fixInstall the library using pip: `pip install faster-coco-eval` (for core functionality) or `pip install faster-coco-eval[extra]` (for full functionality including visualization tools).
ImportError: cannot import name COCO from pycocotools.coco
This error occurs when attempting to use 'faster-coco-eval' as a drop-in replacement for 'pycocotools' but `faster_coco_eval.init_as_pycocotools()` has not been called to patch the imports.
fixAdd `import faster_coco_eval; faster_coco_eval.init_as_pycocotools()` at the beginning of your script, before any `from pycocotools.coco import COCO` or similar imports.
TypeError: _evaluate_predictions_on_coco() got an unexpected keyword argument 'use_fast_impl'
This error typically arises when integrating with frameworks like Detectron2, which may pass a 'use_fast_impl' argument to COCO evaluation functions, but the underlying 'pycocotools' (or an incompatible version) does not support it, even when 'faster-coco-eval' is intended for use.
fixEnsure that `faster_coco_eval.init_as_pycocotools()` is called before evaluation, and if the issue persists, check for framework-specific configurations or update 'detectron2' to a compatible version that handles 'faster-coco-eval' integration correctly.
ValueError: IoU threshold 0.50 not found in iouThrs list
Prior to version 1.7.2, using `extended_metrics` without explicitly including `0.50` in the `iouThrs` list would raise this error.
fixEnsure your `iouThrs` list includes `0.50` (e.g., `iouThrs=[0.50, 0.75, 0.90]`) or update `faster-coco-eval` to version 1.7.2 or later.
Upgrade
Version history
1.7.2latest on PyPI · released Feb 22, 2026
Audit
Dependencies
numpyrequiredFundamental package for scientific computing in Python, used throughout for array operations.
pycocotoolsrequiredAlthough faster-coco-eval is a replacement, pycocotools is listed as a required dependency on PyPI, suggesting it provides underlying structures or format compatibility.
plotlyoptionalRequired for advanced visualization features like metric curves. Included with '[extra]' installation.
opencv-python-headlessoptionalPotentially used for mask API backends and other image processing utilities. Included with '[extra]' installation.