README.md

English | 简体中文

Introduction

MMCV is a foundational library for computer vision research and supports many research projects as below:

• MMClassification: OpenMMLab image classification toolbox and benchmark.
• MMDetection: OpenMMLab detection toolbox and benchmark.
• MMDetection3D: OpenMMLab's next-generation platform for general 3D object detection.
• MMSegmentation: OpenMMLab semantic segmentation toolbox and benchmark.
• MMAction2: OpenMMLab's next-generation action understanding toolbox and benchmark.
• MMTracking: OpenMMLab video perception toolbox and benchmark.
• MMPose: OpenMMLab pose estimation toolbox and benchmark.
• MMEditing: OpenMMLab image and video editing toolbox.
• MMOCR: OpenMMLab text detection, recognition and understanding toolbox.
• MMGeneration: OpenMMLab image and video generative models toolbox.

It provides the following functionalities.

• Universal IO APIs
• Image/Video processing
• Image and annotation visualization
• Useful utilities (progress bar, timer, ...)
• PyTorch runner with hooking mechanism
• Various CNN architectures
• High-quality implementation of common CUDA ops

See the documentation for more features and usage.

Note: MMCV requires Python 3.6+.

Installation

There are two versions of MMCV:

• mmcv-full: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build.
• mmcv: lite, without CUDA ops but all other features, similar to mmcv<1.0.0. It is useful when you do not need those CUDA ops.

Note: Do not install both versions in the same environment, otherwise you may encounter errors like ModuleNotFound. You need to uninstall one before installing the other. Installing the full version is highly recommended if CUDA is available.

a. Install the full version.

Before installing mmcv-full, make sure that PyTorch has been successfully installed following the official guide.

We provide pre-built mmcv packages (recommended) with different PyTorch and CUDA versions to simplify the building.

i. Install the latest version.

The rule for installing the latest mmcv-full is as follows:

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html

Please replace {cu_version} and {torch_version} in the url to your desired one. For example, to install the latest mmcv-full with CUDA 11.1 and PyTorch 1.9.0, use the following command:

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html

Note: mmcv-full is only compiled on PyTorch 1.x.0 because the compatibility usually holds between 1.x.0 and 1.x.1. If your PyTorch version is 1.x.1, you can install mmcv-full compiled with PyTorch 1.x.0 and it usually works well. For example, if your PyTorch version is 1.8.1 and CUDA version is 11.1, you can use the following command to install mmcv-full.

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html

For more details, please refer the the following tables and delete =={mmcv_version}.

ii. Install a specified version.

The rule for installing a specified mmcv-full is as follows:

pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html

First of all, please refer to the Releases and replace {mmcv_version} a specified one. e.g. 1.3.9. Then replace {cu_version} and {torch_version} in the url to your desired versions. For example, to install mmcv-full==1.3.9 with CUDA 11.1 and PyTorch 1.9.0, use the following command:

pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html

For more details, please refer the the following tables.

CUDA	torch 1.9	torch 1.8	torch 1.7	torch 1.6	torch 1.5	torch 1.4	torch 1.3
11.1	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html
11.0			install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html
10.2	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.9.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html
10.1		install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.4.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.3.0/index.html
9.2			install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.4.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.3.0/index.html
cpu	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.9.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.4.0/index.html	install pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.3.0/index.html

Another way is to compile locally by running

pip install mmcv-full

Note that the local compiling may take up to 10 mins.

b. Install the lite version.

pip install mmcv

c. Install full version with custom operators for onnxruntime

• Check here for detailed instruction.

If you would like to build MMCV from source, please refer to the guide.

FAQ

If you face some installation issues, CUDA related issues or RuntimeErrors, you may first refer to this Frequently Asked Questions.

Citation

If you find this project useful in your research, please consider cite:

@misc{mmcv,
    title={{MMCV: OpenMMLab} Computer Vision Foundation},
    author={MMCV Contributors},
    howpublished = {\url{https://github.com/open-mmlab/mmcv}},
    year={2018}
}

Contributing

We appreciate all contributions to improve MMCV. Please refer to CONTRIBUTING.md for the contributing guideline.

License

MMCV is released under the Apache 2.0 license, while some specific operations in this library are with other licenses. Please refer to LICENSES.md for the careful check, if you are using our code for commercial matters.