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

MengzhangLI · web-flow · commit d9eb6d0067bb · 2022-02-15T22:18:39.000+08:00
* Update the installation of MMCV

* use matrix.torch_version

* fix typo in doc

* fix docs

* fix colab

* change docs
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 (有风险)：**
 

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@`
`33`	`33`	`"## Install MMSegmentation\n",`
`34`	`34`	`"This step may take several minutes. \n",`
`35`	`35`	`"\n",`
`36`		`- "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. "`
	`36`	`+ "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. "`
`37`	`37`	`]`
`38`	`38`	`},`
`39`	`39`	`{`
`@@ -67,9 +67,9 @@`
`67`	`67`	`"outputs": [],`
`68`	`68`	`"source": [`
`69`	`69`	`"# Install PyTorch\n",`
`70`		`- "!pip install -U torch==1.5.0+cu101 torchvision==0.6.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html\n",`
	`70`	`+ "!conda install pytorch=1.6.0 torchvision cudatoolkit=10.1 -c pytorch\n",`
`71`	`71`	`"# Install MMCV\n",`
`72`		`- "!pip install mmcv-full==latest+torch1.5.0+cu101 -f https://download.openmmlab.com/mmcv/dist/index.html"`
	`72`	`+ "!pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6/index.html"`
`73`	`73`	`]`
`74`	`74`	`},`
`75`	`75`	`{`