Skip to content

1. Installation

Jump to bottom
WRH edited this page Apr 13, 2022 · 49 revisions

We highly recommend developers follow our best practices to install MMEditing. However, the whole process is highly customizable. See Customize Installation section for more information.

Best Practices

The following steps work on Linux, Windows, and macOS.

Step 0. Download and install Miniconda from official website.

Step 1. Create a conda environment and activate it

conda create --name mmedit python=3.8 -y
conda activate mmedit

Step 2. Install PyTorch following official instructions, e.g.

  • On GPU platforms:

    conda install pytorch=1.10 torchvision cudatoolkit=11.3 -c pytorch

  • On CPU platforms:

    conda install pytorch=1.10 torchvision cpuonly -c pytorch

Step 3. Install pre-built MMCV using MIM.

pip3 install openmim
mim install mmcv-full==1.4.5

Step 4. Install MMEditing from the source code.

git clone https://github.com/open-mmlab/mmediting.git
cd mmediting
pip3 install -e .

Step 5. Verification.

cd ~
python -c "import mmedit; print(mmedit.__version__)"
# Example output: 0.13.0

The installation is successful if the version number is output correctly.

Customize Installation

Version of Dependencies

You may change the version of Python, PyTorch, and MMCV by changing the version numbers in Step 1, 2, and 3, respectively.

Currently, MMEditing works with

Version of CUDA

When installing PyTorch in Step 2, you need to specify the version of CUDA. If you are not clear on which to choose, follow our recommendations:

  1. For Ampere-based NVIDIA GPUs, such as GeForce 30 series and NVIDIA A100, CUDA 11 is a must.
  2. For older NVIDIA GPUs, CUDA 11 is backward compatible, but CUDA 10.2 offers better compatibility and is more lightweight.

Please also make sure the GPU driver satisfies the minimum version requirements. See this table for more information.

Please Note that there is no need to install the complete CUDA toolkit if you follow our best practices because no CUDA code will be compiled. However, if you hope to compile MMCV or other C++/CUDA operators, you need to install the complete CUDA toolkit from NVIDIA's website, and its version should match the CUDA version of PyTorch, which is the version of cudatoolkit in conda install.

Install without Conda

Though we highly recommend using conda to create environments and install PyTorch, it is viable to install PyTorch only with pip, for example, with the following command,

pip3 install torch torchvision

However, an --extra-index-url or -f option is usually required to specify the CPU / CUDA version. See PyTorch website for more details.

Install without MIM

MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex way. MIM solves such dependency automatically and makes installation easier. However, it is not a must.

To install MMCV with pip instead of MIM, please follow MMCV installation guides. This requires manually specifying a find-url based on PyTorch version and its CUDA version.

For example, the following command install mmcv-full built for PyTorch 1.10.x and CUDA 11.3.

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

On macOS

Pre-built MMCV package is not available for macOS, so you have to build MMCV from the source. Pip will build it automatically during installation, but it requires a C++ compiler. A simple solution is to install Clang with xcode-select --install.

Under such circumstances, MIM is not required and pip install mmcv-full -v can do the job. See MMCV installation guides for more details.

On Google Colab

Online machine learning platform such as Google Colab usually has PyTorch installed. Thus we only need to install MMCV and MMEditing with the following commands.

Step 1. Install MMCV using MIM.

!pip3 install openmim
!mim install mmcv-full

Step 2. Install MMEditing from the source.

!git clone https://github.com/open-mmlab/mmediting.git
%cd mmediting
!pip3 install -e .

Step 3. Verification.

import mmedit
print(mmedit.__version__)
# Example output: 0.13.0

Note: within Jupyter, the exclamation mark ! is used to call external executables and %cd is a IPython magic command to change the current working directory of Python.

Additional Notes

Speed up Installation with Mirror

One can configure conda and pip mirrors to speed up the installation. This step is very practical for users geologically in China.

See the below links (in Chinese) for details：

On -e .

You may be curious about what -e . means when supplied with pip install. Here is the description:

  • -e means editable mode. When import mmedit, modules imported are ones located under the current directory. This method is particularly convenient for developers. If some codes are modified, new codes will be imported next time without reinstallation. If pip install without -e, pip installer will copy codes in the current directory to somewhere like lib/python/site-package. Consequently, code modification in the current directory takes no effect unless pip install again.
  • . means code in this directory

You can also use pip -e .[all], which will install more dependencies, especially for pre-commit hooks and unittests.

Clone this wiki locally