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

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

MMPose version MMCV version
master 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-full following the installation instruction.


  • Do I need to reinstall mmpose after some code modifications?

    If you follow the best practice and install mmpose from source, any local modifications made to the code will take effect without reinstallation.

  • How to develop with multiple MMPose versions?

    Generally speaking, we recommend to use different virtual environments to manage MMPose in different working directories. However, you can also use the same environment to develop MMPose in different folders, like mmpose-0.26.0, mmpose-0.25.0. When you run the train or test shell script, it will adopt the mmpose package in the current folder. And when you run other Python script, you can also add PYTHONPATH=`pwd` at the beginning of your command to use the package in the current folder.

    Conversely, to use the default MMPose installed in the environment rather than the one you are working with, you can remove the following line in those shell scripts:

    PYTHONPATH="$(dirname $0)/..":$PYTHONPATH


  • How to convert my 2d keypoint dataset to coco-type?

    You may refer to this conversion tool to prepare your data. Here is an example of the coco-type json. In the coco-type json, we need “categories”, “annotations” and “images”. “categories” contain some basic information of the dataset, e.g. class name and keypoint names. “images” contain image-level information. We need “id”, “file_name”, “height”, “width”. Others are optional. Note: (1) It is okay that “id”s are not continuous or not sorted (e.g. 1000, 40, 352, 333 …).

    “annotations” contain instance-level information. We need “image_id”, “id”, “keypoints”, “num_keypoints”, “bbox”, “iscrowd”, “area”, “category_id”. Others are optional. Note: (1) “num_keypoints” means the number of visible keypoints. (2) By default, please set “iscrowd: 0”. (3) “area” can be calculated using the bbox (area = w * h) (4) Simply set “category_id: 1”. (5) The “image_id” in “annotations” should match the “id” in “images”.

  • 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 if my custom dataset does not have segmentation label?

    Just set the area of the person as the area of the bounding boxes. During evaluation, please set use_area=False as in this example.

  • 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 use_gt_bbox=True and bbox_file=''. Or one can use detected boxes to evaluate the generalizability of models, by setting use_gt_bbox=False and 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/ Test res50 configs/body/2D_Kpt_SV_RGB_Img/topdown_hm/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 Use Pre-Trained Model, in order to use the pre-trained model for the whole network (backbone + head), the new config adds the link of pre-trained models in the load_from.

    And to use backbone for pre-training, you can change pretrained value in the backbone dict of config files to the checkpoint path / url. When training, the unexpected keys will be ignored.

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

    Use TensorboardLoggerHook in log_config like

    log_config=dict(interval=20, hooks=[dict(type='TensorboardLoggerHook')])

    You can refer to and the example config.

  • Log info is NOT printed

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

  • How to fix stages of backbone when finetuning a model ?

    You can refer to def _freeze_stages() and frozen_stages, reminding to set find_unused_parameters = True in config files for distributed training or testing.


  • 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. You can refer to the code for more details.


  • How to run mmpose on CPU?

    Run demos with --device=cpu.

  • How to speed up inference?

    For top-down models, try to edit the config file. For example,

    1. set flip_test=False in topdown-res50.

    2. set post_process='default' in topdown-res50.

    3. use faster human bounding box detector, see MMDetection.

    For bottom-up models, try to edit the config file. For example,

    1. set flip_test=False in AE-res50.

    2. set adjust=False in AE-res50.

    3. set refine=False in AE-res50.

    4. use smaller input image size in AE-res50.


  • Why is the onnx model converted by mmpose throwing error when converting to other frameworks such as TensorRT?

    For now, we can only make sure that models in mmpose are onnx-compatible. However, some operations in onnx may be unsupported by your target framework for deployment, e.g. TensorRT in this issue.

    And please note that pytorch2onnx in MMPose is no longer maintained and will be deprecated in the future. We have MMDeploy to support model deployment for all OpenMMLab codebases including MMPose. You can find details about supported models and user guides in their documentation, and raise issues to request support for the models you would like to use.

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

Free document hosting provided by Read the Docs.