MMSegmentation Installation Guide On Ubuntu 22.0

July 7, 2025 by StackCamp Team 49 views

**Installing MMSegmentation on Ubuntu 22.0: A Comprehensive Guide**

This guide provides a detailed walkthrough for installing MMSegmentation on Ubuntu 22.0. MMSegmentation is a powerful open-source semantic segmentation toolbox based on PyTorch. It is part of the OpenMMLab project and offers a modular framework that simplifies the development and training of segmentation models. This article covers the necessary steps, from creating a Conda environment to running a demo, and addresses common errors you might encounter along the way.

Prerequisites

Before diving into the installation process, ensure you have the following prerequisites in place:

Ubuntu 22.0: This guide is specifically tailored for Ubuntu 22.0.
Anaconda or Miniconda: Conda is a package, dependency, and environment management system. If you don't have it installed, download and install it from the official Anaconda or Miniconda website.
Basic understanding of the command line: Familiarity with navigating directories and executing commands in the terminal is essential.
CUDA-compatible GPU (Optional): If you plan to leverage GPU acceleration, ensure you have an NVIDIA GPU and the appropriate drivers installed. For 4090 and other newer cards, CUDA Toolkit 11.8 or higher is required.

Step-by-Step Installation Guide

Step 1: Create and Activate a Conda Environment

Begin by creating an isolated Conda environment to manage dependencies for MMSegmentation. This helps prevent conflicts with other Python packages installed on your system.

Open your terminal and execute the following command:

conda create --name openmmlab python=3.8 -y

This command creates a new Conda environment named openmmlab with Python 3.8. The -y flag automatically answers "yes" to any prompts during the creation process.

Next, activate the newly created environment:

conda activate openmmlab

Your terminal prompt should now indicate that you are working within the openmmlab environment.

Step 2: Install PyTorch

PyTorch, a widely used open-source machine learning framework, serves as the backbone for MMSegmentation. Installing the correct version of PyTorch is vital for compatibility and to avoid potential errors. For users with newer GPUs like the 4090, installing a lower version of PyTorch initially is recommended. This approach helps ensure compatibility with the CUDA Toolkit, which is crucial for GPU acceleration.

Given that the 4090 GPU requires CUDA Toolkit 11.8 or higher, it's crucial to install a PyTorch version that aligns well with this CUDA version. While the system's CUDA installation is pivotal, the environment's CUDA compatibility is generally backward-compatible, enhancing flexibility.

To install PyTorch with CUDA 11.7, use the following Conda command:

conda install pytorch==1.13.0 torchvision==0.14.0 torchaudio==0.13.0 pytorch-cuda=11.7 -c pytorch -c nvidia

Alternatively, you can use pip:

pip install torch==1.13.0+cu117 torchvision==0.14.0+cu117 torchaudio==0.13.0 --extra-index-url https://download.pytorch.org/whl/cu117

These commands install PyTorch 1.13.0 along with torchvision and torchaudio, specifically built for CUDA 11.7. The -c pytorch -c nvidia flags in the Conda command specify the channels to fetch the packages from, while the --extra-index-url flag in the pip command provides an alternative index URL.

Step 3: Install MMCV using MIM

Before installing MMSegmentation, it's essential to install MMCV (OpenMMLab Computer Vision Foundation), a foundational library for many OpenMMLab projects, including MMSegmentation. MMCV provides common functionalities and components for computer vision tasks.

The recommended way to install MMCV is by using MIM (MMLab Instance Manager), a package manager specifically designed for OpenMMLab projects.

First, install MIM:

pip install -U openmim

Then, install mmengine:

mim install mmengine

Finally, install MMCV with a version greater than or equal to 2.0.0:

mim install "mmcv>=2.0.0"

These commands ensure that you have the necessary base components installed before proceeding with MMSegmentation.

Step 4: Install MMSegmentation

With the environment set up and dependencies installed, you can now install MMSegmentation itself. There are two primary methods for installation:

Option A: Install from Source (for development)

If you plan to actively develop and modify MMSegmentation, installing from source is the preferred method. This allows you to directly edit the codebase and see the changes reflected immediately.

Clone the MMSegmentation repository from GitHub:
```
git clone -b main https://github.com/open-mmlab/mmsegmentation.git
```
This command clones the main branch of the MMSegmentation repository to your local machine.
Navigate to the MMSegmentation directory:
```
cd mmsegmentation
```
Install MMSegmentation in editable mode:
```
pip install -v -e .
```
The -v flag enables verbose mode, providing more detailed output during the installation process. The -e flag installs MMSegmentation in editable mode, which creates symbolic links to the source code, so any changes you make to the code will be reflected without needing to reinstall.

Option B: Install via pip (as a dependency)

If you intend to use MMSegmentation as a library in your project without modifying its source code, you can install it directly via pip:

pip install "mmsegmentation>=1.0.0"

This command installs the latest version of MMSegmentation (or a version greater than or equal to 1.0.0) from PyPI, the Python Package Index.

Step 5: Run a Demo to Verify the Installation

After successfully installing MMSegmentation, it's crucial to verify the installation by running a demo. This ensures that all components are working correctly.

Download Configuration and Checkpoint Files: MMSegmentation uses configuration files to define model architectures and training parameters. Checkpoint files contain the learned weights of a pre-trained model.

Use MIM to download the necessary files:
```
mim download mmsegmentation --config pspnet_r50-d8_4xb2-40k_cityscapes-512x1024 --dest .
```
This command downloads the configuration file (pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py) and the corresponding checkpoint file (pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth) for the PSPNet model trained on the Cityscapes dataset. The --dest . flag specifies that the files should be downloaded to the current directory.

The download process may take a few seconds or longer depending on your network speed. Once completed, you should find the two downloaded files in your current directory.
Run the Inference Demo: MMSegmentation provides a demo script (demo/image_demo.py) that allows you to perform inference on a sample image.

If you installed MMSegmentation from source, run the following command:
```
python demo/image_demo.py demo/demo.png configs/pspnet/pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth --device cuda:0 --out-file result.jpg
```
This command runs the image_demo.py script with the following arguments:
- demo/demo.png: The input image path.
- configs/pspnet/pspnet_r50-d8_4xb2-40k_cityscapes-512x1024.py: The path to the configuration file.
- pspnet_r50-d8_512x1024_40k_cityscapes_20200605_003338-2966598c.pth: The path to the checkpoint file.
- --device cuda:0: Specifies the device to use for inference (GPU 0 in this case). If you don't have a GPU, you can use --device cpu.
- --out-file result.jpg: Specifies the output image file.
After running the command, a new image named result.jpg should be created in the current directory. This image will show the segmentation results overlaid on the input image. If you can view the segmented image, it confirms that MMSegmentation is installed correctly and is functioning as expected.

Troubleshooting Common Errors

During the installation and usage of MMSegmentation, you might encounter some common errors. Here are a couple of frequently occurring issues and their solutions:

Error 1: MMCV Version Incompatibility

Traceback (most recent call last):
  File "demo/image_demo.py", line 6, in <module>
    from mmseg.apis import inference_model, init_model, show_result_pyplot
  File "/home/ubuntu/mmsegmentation/mmseg/__init__.py", line 61, in <module>
    assert (mmcv_min_version <= mmcv_version < mmcv_max_version), \
AssertionError: MMCV==2.2.0 is used but incompatible. Please install mmcv>=2.0.0rc4.

This error indicates that the version of MMCV installed is incompatible with the version required by MMSegmentation. MMSegmentation has specific version requirements for MMCV, and using an incorrect version can lead to this error.

Solution: To resolve this, ensure that you have the correct version of MMCV installed. Follow these steps:

First, try installing a specific compatible version of MMCV using pip:
```
pip install mmcv-lite==2.0.0rc4
```
This command installs the mmcv-lite version 2.0.0rc4, which is often a compatible version for many MMSegmentation releases. The mmcv-lite version is a lightweight version of MMCV that includes only the essential modules, reducing the installation size and complexity.
If the above command does not resolve the issue, you can try installing a different version of MMCV using MIM:
```
mim install mmcv==2.1.0
```
This command uses MIM to install MMCV version 2.1.0. MIM is the recommended way to install MMCV as it handles dependencies and version compatibility effectively.

Error 2: ModuleNotFoundError: No module named 'mmcv._ext'

ModuleNotFoundError: No module named 'mmcv._ext'

This error typically occurs when the MMCV installation is incomplete or corrupted. The mmcv._ext module contains compiled extensions that are essential for MMCV's functionality. If this module is missing, it indicates that the compilation or installation of MMCV's extensions failed.

Solution: To fix this error, try the following steps:

Reinstall MMCV: The first step is to try reinstalling MMCV to ensure that all components are correctly installed. Use MIM to reinstall MMCV:
```
mim install mmcv==2.1.0
```
This command reinstalls MMCV version 2.1.0, ensuring that all necessary modules and extensions are properly installed.
Check CUDA and PyTorch Compatibility: Ensure that your CUDA version, PyTorch version, and MMCV version are compatible with each other. Incompatible versions can lead to compilation and runtime errors. Refer to the MMSegmentation documentation for the recommended versions.
- Verify that your CUDA version is compatible with the PyTorch version you have installed. You can check the PyTorch website or documentation for compatibility information.
- Ensure that the MMCV version you are using supports the CUDA and PyTorch versions in your environment.
Compile MMCV Extensions Manually: In some cases, the MMCV extensions might not be compiled correctly during the installation process. You can try compiling them manually.
- Navigate to the MMCV directory within your Conda environment's site-packages directory. The exact path will depend on your Conda environment and installation location.
- Run the following commands to compile the extensions:
```
cd /path/to/your/conda/envs/openmmlab/lib/python3.8/site-packages/mmcv
python setup.py develop
```
  Replace /path/to/your/conda/envs/openmmlab with the actual path to your Conda environment. This command manually compiles and installs the MMCV extensions.

By following these troubleshooting steps, you should be able to resolve the ModuleNotFoundError and ensure that MMCV is correctly installed and functioning.

Customizing Prediction Results

By default, MMSegmentation displays prediction results with category labels. If you want to remove these labels, you can modify the show_result_pyplot function in your inference script.

Locate the line in your script where you call show_result_pyplot and add the with_labels=False argument:

show_result_pyplot(model, img_path, result, show=False, out_file=output_path, opacity=1, with_labels=False)

This modification will prevent the category labels from being displayed in the output image, providing a cleaner visualization of the segmentation masks.

Conclusion

Installing MMSegmentation on Ubuntu 22.0 can be a straightforward process if you follow the steps outlined in this guide. By creating a Conda environment, installing the necessary dependencies, and verifying the installation with a demo, you can set up MMSegmentation successfully. Additionally, understanding common errors and their solutions will help you troubleshoot any issues that may arise. With MMSegmentation installed, you can explore its powerful capabilities for semantic segmentation and build your own custom models and applications.

This comprehensive guide should help you get started with MMSegmentation on Ubuntu 22.0, enabling you to leverage its features for your segmentation tasks. Remember to consult the official MMSegmentation documentation for more in-depth information and advanced usage.