{"id":2214,"library":"pycocotools","title":"Pycocotools","description":"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.","status":"active","version":"2.0.11","language":"en","source_language":"en","source_url":"https://github.com/ppwwyyxx/cocoapi","tags":["computer-vision","dataset","object-detection","segmentation","keypoint-detection","evaluation"],"install":[{"cmd":"pip install pycocotools","lang":"bash","label":"Standard installation"},{"cmd":"pip install cython numpy && pip install pycocotools","lang":"bash","label":"Installation with explicit dependencies (if issues arise)"}],"dependencies":[{"reason":"Fundamental for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Required to compile C extensions for mask operations, often needs explicit pre-installation.","package":"cython","optional":false},{"reason":"Used for visualization functions (e.g., `showAnns`), but not strictly required for core API usage.","package":"matplotlib","optional":true},{"reason":"Sometimes used in examples or for image loading (e.g., `skimage.io`).","package":"scikit-image","optional":true}],"imports":[{"symbol":"COCO","correct":"from pycocotools.coco import COCO"},{"symbol":"COCOeval","correct":"from pycocotools.cocoeval import COCOeval"},{"symbol":"maskUtils","correct":"from pycocotools import mask as maskUtils"}],"quickstart":{"code":"import os\nfrom pycocotools.coco import COCO\n\n# NOTE: You need to download COCO annotations first.\n# For example, 'instances_val2017.json' can be found at:\n# http://images.cocodataset.org/annotations/annotations_trainval2017.zip\n\n# Placeholder for annotation file path. Replace with actual path.\nannFile = os.environ.get('COCO_ANN_FILE', 'path/to/instances_val2017.json')\n\n# Initialize COCO API for instance annotations\ntry:\n    coco = COCO(annFile)\n    print(f\"Successfully loaded COCO annotations from {annFile}\")\n\n    # Get all image IDs\n    imgIds = coco.getImgIds()\n    print(f\"Total images: {len(imgIds)}\")\n\n    # Get category IDs\n    catIds = coco.getCatIds(catNms=['person', 'dog', 'cat'])\n    print(f\"Categories found: {coco.loadCats(catIds)}\")\n\n    # Pick an image and display some info\n    img = coco.loadImgs(imgIds[0])[0]\n    print(f\"First image info: {img}\")\n\n    # Get annotations for the image\n    annIds = coco.getAnnIds(imgIds=img['id'], catIds=catIds, iscrowd=None)\n    anns = coco.loadAnns(annIds)\n    print(f\"Annotations for image {img['id']}: {len(anns)} found\")\n\nexcept Exception as e:\n    print(f\"Error loading COCO annotations or processing: {e}\")\n    print(\"Please ensure the annotation file path is correct and accessible.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Install 'Desktop development with C++' workload from Visual Studio Build Tools. For Python 3.9+, ensure compatibility with the installed C++ compiler version.","message":"Windows 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.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Replace `E.params.useSegm = True/False` with `E.params.iouType = 'segm'` or `E.params.iouType = 'bbox'` respectively.","message":"The `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.","severity":"breaking","affected_versions":"2.0.0 and later"},{"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).","message":"C-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.","severity":"gotcha","affected_versions":"All versions, especially in complex environments or non-standard OS setups."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}