Fix ModuleNotFoundError: No module named 'mmcv'

Encountering ModuleNotFoundError: No module named 'mmcv' is common when setting up computer vision projects. This error halts your code immediately. It means Python cannot find the MMCV library in your current environment. MMCV is a foundational library for many deep learning models. Fixing this requires understanding your environment and installation method.

The error typically appears after cloning a repository or switching Python environments. It can also happen when you install a package in the wrong environment. Let's break down the solution step by step. You will learn how to diagnose and fix this issue quickly.

Why Does This Error Occur?

MMCV is not a standard library. You must install it separately using a package manager. The error occurs for three main reasons. First, MMCV is not installed at all. Second, it is installed in a different Python environment than the one you are using. Third, you have installed the wrong version for your PyTorch or CUDA setup.

Sometimes, the issue is simpler. You might have multiple Python installations on your system. Your IDE might use a different interpreter than your terminal. Always check your active environment first.

Step 1: Check Your Current Environment

Before installing anything, verify which Python and pip you are using. Run these commands in your terminal or command prompt.

 
    which python
    which pip
    python --version
    pip --version
    

For Windows, use where instead of which. This shows the exact paths. If the paths do not match, you are using different environments. This mismatch is a frequent cause of missing modules.

If you use virtual environments, activate the correct one first. For conda users, run conda activate your_env_name. This ensures your installation goes to the right place.

Step 2: Install MMCV Correctly

MMCV offers two main versions: mmcv and mmcv-lite. The full version includes compiled CUDA operations. The lite version is for CPU-only or basic usage. Choose based on your needs.

The official recommendation is to install using the openmim tool. It automatically detects your PyTorch and CUDA versions. Run the following commands.

 
    pip install -U openmim
    mim install mmcv
    

This method is safe and avoids version conflicts. If you need a specific version, use the mmcv-full package. For example, to install version 1.7.0, run:

 
    pip install mmcv-full==1.7.0
    

For the latest 2.x versions, just use pip install mmcv. Always check the official MMCV documentation for compatibility. This is crucial for GPU support.

Step 3: Install from Source (Alternative)

If the pre-built wheels fail, you can build from source. This is useful for custom CUDA versions or unusual setups. First, clone the repository.

 
    git clone https://github.com/open-mmlab/mmcv.git
    cd mmcv
    pip install -e . -v
    

This process compiles the code on your machine. It takes more time but ensures compatibility. Ensure you have a C++ compiler and CUDA toolkit installed if needed.

Building from source can fail if dependencies are missing. Install ninja and torch first. Then retry the build. This method gives you full control over the installation.

Step 4: Verify the Installation

After installation, test if MMCV is accessible. Run a simple Python import command.

 
    import mmcv
    print(mmcv.__version__)
    

If it prints a version number, the installation is successful. If you see a new error, check the message. It might mention missing torch or numpy. Install those dependencies first.

For a more thorough check, run mmcv.utils.collect_env(). This function prints your environment details. It helps diagnose version mismatches.

 
    from mmcv.utils import collect_env
    print(collect_env())
    

Review the output for PyTorch, CUDA, and MMCV versions. They should be compatible. If not, reinstall with the correct version.

Common Pitfalls and Solutions

Many users install MMCV with pip without specifying a version. This often installs the CPU-only version. If you need GPU support, install the full version. Use pip install mmcv-full for older versions. For newer versions, pip install mmcv includes GPU support.

Another common issue is using the wrong Python interpreter in your IDE. In VS Code, click the interpreter selector at the bottom. Choose the one where you installed MMCV. This simple step resolves many "module not found" errors.

Also, avoid using sudo pip on Linux. It installs to the system Python, not your virtual environment. Always use pip install --user or activate your virtual environment first.

When to Use mmcv vs mmcv-lite

Choose mmcv-lite if you only need basic operations and do not require custom CUDA kernels. It is lighter and installs faster. Use the full mmcv for training or inference with models that use custom ops.

Most modern projects require the full version. Check your project's requirements.txt file. It will specify which version to use. Follow that instruction to avoid runtime errors.

If you are unsure, start with the full version. It is backward compatible with lite features. This reduces the risk of missing functionality later.

Conclusion

The ModuleNotFoundError: No module named 'mmcv' is straightforward to fix. Start by checking your environment paths. Then install MMCV using mim or pip. Verify the installation with a simple import. If issues persist, build from source or check your IDE interpreter.

Always keep your PyTorch and CUDA versions in mind. MMCV is tightly coupled with these libraries. Using mismatched versions causes subtle bugs. With these steps, you can resolve the error and continue your computer vision work without delays.

For more Python debugging tips, explore our guide on common Python errors. If you work with deep learning, check our PyTorch setup guide. And for environment management, read our virtual environment best practices.