We list some common issues faced by many users and their corresponding solutions here. Feel free to enrich the list if you find any frequent issues and have ways to help others to solve them. If the contents here do not cover your issue, please create an issue using the provided templates and make sure you fill in all required information in the template.


Compatibility issue between MMCV and MMPose; “AssertionError: MMCV==xxx is used but incompatible. Please install mmcv>=xxx, <=xxx.”

Here are the version correspondences between mmdet, mmcv and mmpose:

  • mmdet 2.x <=> mmpose 0.x <=> mmcv 1.x

  • mmdet 3.x <=> mmpose 1.x <=> mmcv 2.x

Detailed compatible MMPose and MMCV versions are shown as below. Please choose the correct version of MMCV to avoid installation issues.

MMPose 1.x

MMPose version MMCV/MMEngine version
1.3.1 mmcv>=2.0.1, mmengine>=0.9.0
1.3.0 mmcv>=2.0.1, mmengine>=0.9.0
1.2.0 mmcv>=2.0.1, mmengine>=0.8.0
1.1.0 mmcv>=2.0.1, mmengine>=0.8.0
1.0.0 mmcv>=2.0.0, mmengine>=0.7.0
1.0.0rc1 mmcv>=2.0.0rc4, mmengine>=0.6.0
1.0.0rc0 mmcv>=2.0.0rc0, mmengine>=0.0.1
1.0.0b0 mmcv>=2.0.0rc0, mmengine>=0.0.1

MMPose 0.x

MMPose version MMCV version
0.x mmcv-full>=1.3.8, \<1.8.0
0.29.0 mmcv-full>=1.3.8, \<1.7.0
0.28.1 mmcv-full>=1.3.8, \<1.7.0
0.28.0 mmcv-full>=1.3.8, \<1.6.0
0.27.0 mmcv-full>=1.3.8, \<1.6.0
0.26.0 mmcv-full>=1.3.8, \<1.6.0
0.25.1 mmcv-full>=1.3.8, \<1.6.0
0.25.0 mmcv-full>=1.3.8, \<1.5.0
0.24.0 mmcv-full>=1.3.8, \<1.5.0
0.23.0 mmcv-full>=1.3.8, \<1.5.0
0.22.0 mmcv-full>=1.3.8, \<1.5.0
0.21.0 mmcv-full>=1.3.8, \<1.5.0
0.20.0 mmcv-full>=1.3.8, \<1.4.0
0.19.0 mmcv-full>=1.3.8, \<1.4.0
0.18.0 mmcv-full>=1.3.8, \<1.4.0
0.17.0 mmcv-full>=1.3.8, \<1.4.0
0.16.0 mmcv-full>=1.3.8, \<1.4.0
0.14.0 mmcv-full>=1.1.3, \<1.4.0
0.13.0 mmcv-full>=1.1.3, \<1.4.0
0.12.0 mmcv-full>=1.1.3, \<1.3
0.11.0 mmcv-full>=1.1.3, \<1.3
0.10.0 mmcv-full>=1.1.3, \<1.3
0.9.0 mmcv-full>=1.1.3, \<1.3
0.8.0 mmcv-full>=1.1.1, \<1.2
0.7.0 mmcv-full>=1.1.1, \<1.2
  • Unable to install xtcocotools

    1. Try to install it using pypi manually pip install xtcocotools.

    2. If step1 does not work. Try to install it from source.

    git clone
    cd xtcocoapi
    python install
  • No matching distribution found for xtcocotools>=1.6

    1. Install cython by pip install cython.

    2. Install xtcocotools from source.

    git clone
    cd xtcocoapi
    python install
  • “No module named ‘mmcv.ops’”; “No module named ‘mmcv._ext’”

    1. Uninstall existing mmcv in the environment using pip uninstall mmcv.

    2. Install mmcv following mmcv installation instruction.


  • What if my custom dataset does not have bounding box label?

    We can estimate the bounding box of a person as the minimal box that tightly bounds all the keypoints.

  • What is COCO_val2017_detections_AP_H_56_person.json? Can I train pose models without it?

    “COCO_val2017_detections_AP_H_56_person.json” contains the “detected” human bounding boxes for COCO validation set, which are generated by FasterRCNN. One can choose to use gt bounding boxes to evaluate models, by setting bbox_file=None in val_dataloader.dataset in config. Or one can use detected boxes to evaluate the generalizability of models, by setting bbox_file='COCO_val2017_detections_AP_H_56_person.json'.


  • RuntimeError: Address already in use

    Set the environment variables MASTER_PORT=XXX. For example:

    MASTER_PORT=29517 GPUS=16 GPUS_PER_NODE=8 CPUS_PER_TASK=2 ./tools/ train res50 configs/body_2d_keypoint/topdown_regression/coco/ work_dirs/res50_coco_256x192
  • “Unexpected keys in source state dict” when loading pre-trained weights

    It’s normal that some layers in the pretrained model are not used in the pose model. ImageNet-pretrained classification network and the pose network may have different architectures (e.g. no classification head). So some unexpected keys in source state dict is actually expected.

  • How to use trained models for backbone pre-training ?

    Refer to Migration - Step3: Model - Backbone.

    When training, the unexpected keys will be ignored.

  • How to visualize the training accuracy/loss curves in real-time ?

    Modify vis_backends in config file like:

    vis_backends = [

    You can refer to user_guides/

  • Log info is NOT printed

    Use smaller log interval. For example, change interval=50 to interval=1 in the config:

    # hooks
    default_hooks = dict(logger=dict(interval=1))


  • How to evaluate on MPII test dataset? Since we do not have the ground-truth for test dataset, we cannot evaluate it ‘locally’. If you would like to evaluate the performance on test set, you have to upload the pred.mat (which is generated during testing) to the official server via email, according to the MPII guideline.

  • For top-down 2d pose estimation, why predicted joint coordinates can be out of the bounding box (bbox)? We do not directly use the bbox to crop the image. bbox will be first transformed to center & scale, and the scale will be multiplied by a factor (1.25) to include some context. If the ratio of width/height is different from that of model input (possibly 192/256), we will adjust the bbox.


  • How to run mmpose on CPU?

    Run demos with --device=cpu.

  • How to speed up inference?

    A few approaches may help to improve the inference speed:

    1. Set flip_test=False in init_cfg in the config file.

    2. For top-down models, use faster human bounding box detector, see MMDetection.

  • What is the definition of each keypoint index?

    Check the meta information file for the dataset used to train the model you are using. They key keypoint_info includes the definition of each keypoint.

Read the Docs v: latest
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.