# open-mmlab/mmcv: the CUDA ops and data pipeline layer under OpenMMLab detectors

> MMCV is the foundation library that OpenMMLab detection, segmentation and pose models sit on. This covers what mmcv and mmcv-lite each contain, how to install them with mim, and why a mismatched PyTorch or CUDA build sends you to a source compile.

**open-mmlab/mmcv** — OpenMMLab Computer Vision Foundation

- Repository: https://github.com/open-mmlab/mmcv
- Website: https://mmcv.readthedocs.io/en/latest/
- Stars: 6,475 · Forks: 1,769
- Language: Python
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/open-mmlab-mmcv

## What MMCV is for, and who ends up installing it

MMCV describes itself as a foundational library for computer vision research. In practice it is the shared substrate under the OpenMMLab model zoo: image and video processing, image and annotation visualization, image transformation, a set of CNN architectures, and high-quality implementations of common CPU and CUDA operators. If you have ever run a config file from MMDetection, MMDetection3D, MMOCR or MMPose, you have already depended on mmcv whether or not you installed it deliberately.

The audience is narrow but deep. It is researchers and engineers who train or fine-tune detection, segmentation and pose models, and who need operators such as deformable convolution or ROIAlign that are not in stock PyTorch at the speed they need. It is not a general-purpose imaging library, and treating it as one is the most common way to waste an afternoon on a compile.

The 2.x line changed the package boundary in a way that still confuses people. The README states that starting from 2.x the package formerly called mmcv was renamed mmcv-lite, and the package formerly called mmcv-full was renamed mmcv. The names swapped meaning. A tutorial written in 2022 that says pip install mmcv-full is describing what is now plain mmcv, and a requirements file pinned to mmcv<2 is describing the old full build.

## How the two distributions split, and what 2.x removed

The repository ships two installable packages from one source tree. mmcv is the comprehensive build with full features and various CUDA ops out of the box, and the README notes it takes longer to build. mmcv-lite has no CUDA ops but all other features, which the README compares to mmcv before 1.0.0.

The README is explicit that you must not install both in the same environment, because you may encounter errors like ModuleNotFound, and that you need to uninstall one before installing the other. That is a real operational constraint, not a footnote: in a shared conda environment where one project pinned mmcv-lite and another needs the ops, the failure surfaces as an import error deep inside a model constructor rather than at install time.

The other structural change is subtraction. MMCV v2.0.0 was released on April 6, 2023, and the README states that in version 2.x it removed components related to the training process and added a data transformation module. Those training components, the runner and the loop, moved to MMEngine, which the OpenMMLab team released on September 1, 2022 and which the README describes as providing a universal runner and a more customizable training process. So a 1.x codebase that calls mmcv.runner does not move to 2.x by changing a version pin; the import path itself is gone.

The setup.py confirms the CUDA-side surface area. It probes torch for Parrots, MLU, MUSA and SUPA backends, each with a FORCE_* environment variable override, before falling back to torch.utils.cpp_extension. That is a wider hardware matrix than most vision libraries attempt, and it is also why wheel availability is version-specific.

## Installing mmcv and mmcv-lite with mim

The README requires Python 3.7+ and states that PyTorch must already be installed following the PyTorch official installation guide before you install mmcv. For Apple silicon users it says to use PyTorch 1.13+.

The documented path goes through openmim rather than pip directly:

```bash
pip install -U openmim
mim install mmcv
```

mim resolves a wheel from the OpenMMLab download index that matches your PyTorch and CUDA versions. To pin a release, the README gives this form:

```bash
mim install mmcv==2.0.0
```

The lite build skips the CUDA ops and is correspondingly simpler:

```bash
pip install -U openmim
mim install mmcv-lite
```

After either command, importing the package and printing mmcv.__version__ should return the version you asked for. The failure mode worth watching for is documented in the README itself: if the install resolves a source package ending in .tar.gz instead of a wheel ending in .whl, there is no pre-built package for your PyTorch, CUDA or mmcv combination, and you have to build mmcv from source. The README shows both logs side by side so you can tell which one you got. A source build on a machine without a full CUDA toolkit is where most installation issues reported against this project originate.

## Where MMCV stops being the right dependency

The clearest boundary is the training loop. Because 2.x removed the training-process components, anything you would call a runner, a hook system or a checkpoint workflow lives in MMEngine. If your work is model training infrastructure rather than vision operators, MMCV is the wrong layer to reach for, and you will end up installing it as a transitive dependency of something else anyway.

The second boundary is the lite split itself. If you need image reading, colour conversion, geometric transforms or visualization and nothing else, mmcv-lite gives you that without a CUDA toolchain, and the README frames it exactly that way: useful when you do not need those CUDA ops. Pulling the full build for a CPU-only preprocessing script means compiling extensions you will never call.

The third is version drift. The README badges PyTorch 1.8 to 2.0 and CUDA 10.1 to 11.8. Those are the tested combinations, and the wheel index is organised by exactly those pairs. A newer PyTorch or a newer CUDA toolkit is not covered by that range, so the practical outcome is a source build rather than an install failure, which is slower to diagnose.

Finally, branch maintenance. MMCV maintains both 1.x, corresponding to the original master branch, and 2.x, corresponding to main, which is now the default branch. The README links a branch maintenance plan for details. If you are pinned to 1.x, you are on a branch the project keeps alive but does not lead with, and new work in the OpenMMLab ecosystem targets 2.x.

## MMCV against plain PyTorch and torchvision

The honest comparison is not against another vision framework but against writing the same operators yourself on top of PyTorch and torchvision. Torchvision gives you standard convolutions, resizing and a transform pipeline. MMCV's difference is the operator set: the README points to high-quality implementations of common CPU and CUDA ops, which in the OpenMMLab configs means kernels like deformable convolution, ROIAlign and NMS variants that torchvision either does not ship or does not ship in the exact form those configs expect.

There is a second difference in the transformation layer. Version 2.x added a data transformation module, and the README links separate documentation pages for data processing and data transform, which suggests the two are distinct concerns in the API rather than one pipeline. That separation is what lets a config declare its augmentation stack as data rather than code.

The cost of that difference is build complexity. Torchvision installs as a wheel for essentially every supported combination. MMCV's CUDA ops mean the wheel must be built per PyTorch and CUDA pair, which is why the README devotes a section to distinguishing wheel downloads from source downloads. If your model uses no custom operators, torchvision is the lower-friction choice and MMCV adds nothing but a build step.

## Versioning, licence and what an upgrade actually costs

The release cadence visible in the tags is uneven. v2.2.0 was tagged on 2024-04-24, v2.1.0 on 2023-10-17, and v1.7.2 on 2023-12-29 on the 1.x line. The repository itself is not archived, and the last push to the default branch was on 2026-09-28, so the codebase is still receiving commits even though the most recent tagged release predates that by a wide margin. Anyone planning a deployment should read that gap as: pin a tag rather than tracking main, and do not assume a new release is imminent.

The licence is Apache-2.0, and the repository carries a LICENSES.md alongside LICENSE, which usually signals bundled third-party components with their own terms. Apache-2.0 is permissive and includes an explicit patent grant, but if you redistribute a build, the notices file is the one to read. That is a description of what is in the repository, not legal advice.

The upgrade cost between 1.x and 2.x is the highest of any step here, because of the removal of training components and the package rename. A migration touches import paths, the runner, and the dependency name in your own packaging. Within 2.x, the changes are smaller, but the wheel index means a PyTorch upgrade can force a source rebuild even when the MMCV version does not change. Budget for that rebuild whenever you move PyTorch, not only when you move MMCV.

## Conclusion

Adopt mmcv if you are running or fine-tuning an OpenMMLab detector, segmenter or pose model and need the CUDA ops those configs reference; the README states that installing the full version is highly recommended if CUDA is available, and warns against having mmcv and mmcv-lite in the same environment. Do not adopt it as a general image-processing utility if you only need resizing and colour conversion, because mmcv-lite covers that without a CUDA toolchain, and do not adopt it as a training loop, because that responsibility moved to MMEngine in the 2.x line. Before committing, verify three things: that your PyTorch version falls inside the 1.8 to 2.0 range the README badges, that your CUDA version falls inside 10.1 to 11.8, and that mim install resolves a .whl rather than a .tar.gz, since the README says a source package means no pre-built wheel exists for your combination.

## FAQ

### What is the difference between mmcv and mmcv-lite in open-mmlab/mmcv?

mmcv is the comprehensive build with full features and various CUDA ops out of the box, and it takes longer to build. mmcv-lite has no CUDA ops but all other features, and the README compares it to mmcv before 1.0.0. The README states you must not install both in the same environment.

### How do I install mmcv with pip or mim?

The README's documented path is to run pip install -U openmim and then mim install mmcv, after PyTorch has already been installed. A specific version can be requested with mim install mmcv==2.0.0. If the install downloads a .tar.gz instead of a .whl, there is no pre-built package for your PyTorch or CUDA combination and you need to build from source.

### Why does installing mmcv take so long or build from source?

The README explains that if the installation command uses a source package ending in .tar.gz rather than a pre-built .whl, there may be no pre-build package corresponding to your PyTorch, CUDA or mmcv version, in which case you build mmcv from source. The full mmcv build is the one with CUDA ops, and the README notes it takes longer to build than mmcv-lite.

## Sources

- [License: Apache-2.0](https://github.com/open-mmlab/mmcv/blob/main/LICENSE)
- [open-mmlab/mmcv on GitHub](https://github.com/open-mmlab/mmcv)
- [Project website](https://mmcv.readthedocs.io/en/latest/)
- [README](https://github.com/open-mmlab/mmcv/blob/main/README.md)
- [Releases](https://github.com/open-mmlab/mmcv/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/open-mmlab-mmcv