[Enhancement] Update the installation of MMCV (open-mmlab#1275)

* Update the installation of MMCV * use matrix.torch_version * fix typo in doc * fix docs * fix colab * change docs
bowenroom · Feb 15, 2022 · 8e8cb06 · 8e8cb06
1 parent 4d451a0
commit 8e8cb06
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 27 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -31,20 +31,20 @@ jobs:
         torch: [1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.9.0]
         include:
           - torch: 1.5.1
+            torch_version: torch1.5
             torchvision: 0.6.1
-            mmcv: 1.5.0
           - torch: 1.6.0
+            torch_version: torch1.6
             torchvision: 0.7.0
-            mmcv: 1.6.0
           - torch: 1.7.0
+            torch_version: torch1.7
             torchvision: 0.8.1
-            mmcv: 1.7.0
           - torch: 1.8.0
+            torch_version: torch1.8
             torchvision: 0.9.0
-            mmcv: 1.8.0
           - torch: 1.9.0
+            torch_version: torch1.9
             torchvision: 0.10.0
-            mmcv: 1.9.0
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}
@@ -60,7 +60,7 @@ jobs:
         run: pip install torch==${{matrix.torch}}+cpu torchvision==${{matrix.torchvision}}+cpu -f https://download.pytorch.org/whl/torch_stable.html
       - name: Install MMCV
         run: |
-          pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cpu/torch${{matrix.mmcv}}/index.html
+          pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cpu/${{matrix.torch_version}}/index.html
           python -c 'import mmcv; print(mmcv.__version__)'
       - name: Install unittest dependencies
         run: |
@@ -98,21 +98,17 @@ jobs:
           ]
         include:
           - torch: 1.5.1+cu101
-            torch_version: torch1.5.1
+            torch_version: torch1.5
             torchvision: 0.6.1+cu101
-            mmcv: 1.5.0
           - torch: 1.6.0+cu101
-            torch_version: torch1.6.0
+            torch_version: torch1.6
             torchvision: 0.7.0+cu101
-            mmcv: 1.6.0
           - torch: 1.7.0+cu101
-            torch_version: torch1.7.0
+            torch_version: torch1.7
             torchvision: 0.8.1+cu101
-            mmcv: 1.7.0
           - torch: 1.8.0+cu101
-            torch_version: torch1.8.0
+            torch_version: torch1.8
             torchvision: 0.9.0+cu101
-            mmcv: 1.8.0
 
     steps:
       - uses: actions/checkout@v2
@@ -133,7 +129,7 @@ jobs:
       - name: Install mmseg dependencies
         run: |
           python -V
-          python -m pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch${{matrix.mmcv}}/index.html
+          python -m pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/${{matrix.torch_version}}/index.html
           python -m pip install -r requirements.txt
           python -c 'import mmcv; print(mmcv.__version__)'
       - name: Build and install
@@ -174,9 +170,8 @@ jobs:
         torch: [1.9.0+cu102]
         include:
           - torch: 1.9.0+cu102
-            torch_version: torch1.9.0
+            torch_version: torch1.9
             torchvision: 0.10.0+cu102
-            mmcv_link: 1.9.0
 
     steps:
       - uses: actions/checkout@v2
@@ -197,7 +192,7 @@ jobs:
       - name: Install mmseg dependencies
         run: |
           python -V
-          python -m pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu102/torch${{matrix.mmcv_link}}/index.html
+          python -m pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu102/${{matrix.torch_version}}/index.html
           python -m pip install -r requirements.txt
           python -c 'import mmcv; print(mmcv.__version__)'
       - name: Build and install

diff --git a/demo/MMSegmentation_Tutorial.ipynb b/demo/MMSegmentation_Tutorial.ipynb
@@ -33,7 +33,7 @@
     "## Install MMSegmentation\n",
     "This step may take several minutes. \n",
     "\n",
-    "We use PyTorch 1.5.0 and CUDA 10.1 for this tutorial. You may install other versions by changing the version number in pip install command. "
+    "We use PyTorch 1.6 and CUDA 10.1 for this tutorial. You may install other versions by change the version number in pip install command. "
    ]
   },
   {
@@ -67,9 +67,9 @@
    "outputs": [],
    "source": [
     "# Install PyTorch\n",
-    "!pip install -U torch==1.5.0+cu101 torchvision==0.6.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html\n",
+    "!conda install pytorch=1.6.0 torchvision cudatoolkit=10.1 -c pytorch\n",
     "# Install MMCV\n",
-    "!pip install mmcv-full==latest+torch1.5.0+cu101 -f https://download.openmmlab.com/mmcv/dist/index.html"
+    "!pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6/index.html"
    ]
   },
   {

diff --git a/docs/en/get_started.md b/docs/en/get_started.md
@@ -57,12 +57,36 @@ Either `mmcv` or `mmcv-full` is compatible with MMSegmentation, but for methods
 
 **Install mmcv for Linux:**
 
-The pre-build mmcv-full (with PyTorch 1.6 and CUDA 10.1) can be installed by running: (other available versions could be found [here](https://mmcv.readthedocs.io/en/latest/#install-with-pip))
+Install MMCV, we recommend you to install the pre-built mmcv as below.
 
 ```shell
-pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html
+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. 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, to install the ``mmcv-full`` with ``CUDA 10.1`` and ``PyTorch 1.6.0``, use the following command:
+
+```shell
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6/index.html
+```
+
+See [here](https://github.com/open-mmlab/mmcv#installation) for different versions of MMCV compatible to different PyTorch and CUDA versions.
+
+Optionally you can choose to compile mmcv from source by the following command
+
+```shell
+git clone https://github.com/open-mmlab/mmcv.git
+cd mmcv
+MMCV_WITH_OPS=1 pip install -e .  # package mmcv-full, which contains cuda ops, will be installed after this step
+# OR pip install -e .  # package mmcv, which contains no cuda ops, will be installed after this step
+cd ..
 ```
 
+**Important:** You need to run `pip uninstall mmcv` first if you have mmcv installed. Because if `mmcv` and `mmcv-full` are both installed, there will be `ModuleNotFoundError`.
+
+
 **Install mmcv for Windows (Experimental):**
 
 For Windows, the installation of MMCV requires native C++ compilers, such as cl.exe. Please add the compiler to %PATH%.

diff --git a/docs/zh_cn/get_started.md b/docs/zh_cn/get_started.md
@@ -57,14 +57,35 @@ c. 按照 [官方教程](https://mmcv.readthedocs.io/en/latest/#installation)
 
 **在 Linux 下安装 mmcv：**
 
-通过运行
+为了安装 MMCV, 我们推荐使用下面的这种预编译好的 MMCV.
 
 ```shell
-pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
 ```
 
-可以安装好 mmcv-full (PyTorch 1.5 和 CUDA 10.1) 版本。
-其他 PyTorch 和 CUDA 版本的 MMCV 安装请参照[这里](https://mmcv.readthedocs.io/en/latest/#install-with-pip)
+请替换 url 里面的 ``{cu_version}`` 和 ``{torch_version}`` 为您想要使用的版本. mmcv-full 仅在
+PyTorch 1.x.0 上面编译, 因为在 1.x.0 和 1.x.1 之间通常是兼容的. 如果您的 PyTorch 版本是 1.x.1,
+您可以安装用 PyTorch 1.x.0 编译的 mmcv-full 而它通常是可以正常使用的.
+例如, 用 ``CUDA 10.1`` and ``PyTorch 1.6.0`` 安装使用 ``mmcv-full``, 使用如下命令:
+
+```shell
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6/index.html
+```
+
+请查看 [这里](https://github.com/open-mmlab/mmcv#installation) 来找到适配不同 PyTorch 和 CUDA 版本的 MMCV.
+
+您也可以采用下面的命令来从源码编译 MMCV (可选)
+
+```shell
+git clone https://github.com/open-mmlab/mmcv.git
+cd mmcv
+MMCV_WITH_OPS=1 pip install -e .  # package mmcv-full, which contains cuda ops, will be installed after this step
+# OR pip install -e .  # package mmcv, which contains no cuda ops, will be installed after this step
+cd ..
+```
+
+**重点:** 如果您已经安装了 MMCV, 您需要先运行 `pip uninstall mmcv`. 因为如果 `mmcv` 和 `mmcv-full` 被同时安装, 将会报错 `ModuleNotFoundError`.
+
 
 **在 Windows 下安装 mmcv (有风险)：**