[Docs] rewrite install.md (#317)

* rewrite the install.md * add faq.md * fix lint * add FAQ to README * add Chinese version * fix typo * fix format * remove modification * fix format
open-mmlab · May 27, 2022 · ced3196 · ced3196
1 parent 90a73f1
commit ced3196
Show file tree

Hide file tree

Showing 4 changed files with 289 additions and 228 deletions.
diff --git a/docs/en/faq.md b/docs/en/faq.md
@@ -0,0 +1,20 @@
+# FAQ
+
+We list some common troubles faced by many users and their corresponding solutions here. Feel free to enrich the list if you find any frequent issues and have ways to help others to solve them. If the contents here do not cover your issue, please create an issue using the [provided templates](https://github.com/open-mmlab/mmselfsup/tree/master/.github/ISSUE_TEMPLATE) and make sure you fill in all required information in the template.
+
+## Installation
+
+Compatible MMCV, MMClassification, MMDetection and MMSegmentation versions are shown below. Please install the correct version of them to avoid installation issues.
+
+| MMSelfSup version |    MMCV version     |  MMClassification version   | MMSegmentation version | MMDetection version |
+| :---------------: | :-----------------: | :-------------------------: | :--------------------: | :-----------------: |
+|  0.9.0 (master)   | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.19.0   |
+|       0.8.0       | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.19.0   |
+|       0.7.1       | mmcv-full >= 1.3.16 | mmcls >= 0.19.0, \<= 0.20.1 |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+|       0.6.0       | mmcv-full >= 1.3.16 |       mmcls >= 0.19.0       |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+|       0.5.0       | mmcv-full >= 1.3.16 |              /              |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+
+**Note:**
+
+- You need to run `pip uninstall mmcv` first if you have mmcv installed. If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
+- If you still have version problem, please create an issue and provide your package versions.
diff --git a/docs/en/install.md b/docs/en/install.md
@@ -1,134 +1,143 @@
-# Installation
-
-## Requirements
+# Prerequisites
 
-- Linux (Windows is not officially supported)
-- Python 3.6+
-- PyTorch 1.5+
-- CUDA 9.2+
-- GCC 5+
-- [mmcv](https://github.com/open-mmlab/mmcv) 1.4.2+
-- [mmcls](https://mmclassification.readthedocs.io/en/latest/install.html) 0.21.0+
-- [mmdet](https://mmdetection.readthedocs.io/en/latest/get_started.html#installation) 2.16.0+
-- [mmseg](https://mmsegmentation.readthedocs.io/en/latest/get_started.html#installation) 0.20.2+
+In this section we demonstrate how to prepare an environment with PyTorch.
 
-Compatible MMCV, MMClassification, MMDetection and MMSegmentation versions are shown below. Please install the correct version of them to avoid installation issues.
+MMselfSup works on Linux (Windows and macOS are not officially supported). It requires Python 3.6+, CUDA 9.2+ and PyTorch 1.5+.
 
-| MMSelfSup version |    MMCV version     |  MMClassification version   | MMSegmentation version | MMDetection version |
-| :---------------: | :-----------------: | :-------------------------: | :--------------------: | :-----------------: |
-|  0.9.0 (master)   | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
-|       0.8.0       | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
-|       0.7.1       | mmcv-full >= 1.3.16 | mmcls >= 0.19.0, \<= 0.20.1 |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
-|       0.6.0       | mmcv-full >= 1.3.16 |       mmcls >= 0.19.0       |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
-|       0.5.0       | mmcv-full >= 1.3.16 |              /              |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+If you are experienced with PyTorch and have already installed it, just skip this part and jump to the [next section](#installation). Otherwise, you can follow these steps for the preparation.
 
-**Note:**
+**Step 0.** Download and install Miniconda from the [official website](https://docs.conda.io/en/latest/miniconda.html).
 
-- You need to run `pip uninstall mmcv` first if you have mmcv installed. If mmcv and mmcv-full are both installed, there will be `ModuleNotFoundError`.
-- As MMSelfSup imports some backbones from MMClassification, you need to install MMClassification before using MMSelfSup.
-- If you don't run MMDetection and MMSegmentation benchmark, it is unnecessary to install them.
+**Step 1.** Create a conda environment and activate it.
 
-## Prepare environment
+```shell
+conda create --name openmmlab python=3.8 -y
+conda activate openmmlab
+```
 
-1. Create a conda virtual environment and activate it.
+**Step 2.** Install PyTorch following [official instructions](https://pytorch.org/get-started/locally/), e.g.
 
-   ```shell
-   conda create -n openmmlab python=3.7 -y
-   conda activate openmmlab
-   ```
+On GPU platforms:
 
-2. Install PyTorch and torchvision following the [official instructions](https://pytorch.org/), e.g.,
+```shell
+conda install pytorch torchvision -c pytorch
+```
 
-   ```shell
-   conda install pytorch torchvision -c pytorch
-   ```
+On CPU platforms:
 
-   Make sure that your compilation CUDA version and runtime CUDA version match. You can check the supported CUDA version for precompiled packages on the [PyTorch website](https://pytorch.org/).
+```shell
+conda install pytorch torchvision cpuonly -c pytorch
+```
 
-   `E.g.1` If you have CUDA 10.1 installed under `/usr/local/cuda` and would like to install PyTorch 1.7, you need to install the prebuilt PyTorch with CUDA 10.1.
+# Installation
 
-   ```shell
-   conda install pytorch==1.7.0 torchvision==0.8.0 cudatoolkit=10.1 -c pytorch
-   ```
+We recommend that users follow our best practices to install MMSelfSup. However, the whole process is highly customizable. See [Customize Installation](#customized-installation) section for more information.
 
-   If you build PyTorch from source instead of installing the prebuilt package, you can use more CUDA versions such as 9.0.
+## Best Practices
 
-## Install MMSelfSup
+**Step 0.** Install [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
 
-1. Install MMCV and MMClassification
+```shell
+pip install -U openmim
+mim install mmcv-full
+```
 
-   ```shell
-   pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
-   ```
+**Step 1.** Install MMSelfSup.
 
-   Please replace `{cu_version}` and `{torch_version}` in the url to your desired one. For example, to install the latest `mmcv-full` with `CUDA 11.0` and `PyTorch 1.7.x`, use the following command:
+Case a: If you develop and run mmselfsup directly, install it from source:
 
-   ```shell
-   pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7/index.html
-   ```
+```shell
+git clone https://github.com/open-mmlab/mmselfsup.git
+cd mmselfsup
+pip install -v -e .
+# "-v" means verbose, or more output
+# "-e" means installing a project in editable mode,
+# thus any local modifications made to the code will take effect without reinstallation.
+```
 
-   - 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.
+Case b: If you use mmselfsup as a dependency or third-party package, install it with pip:
 
-   See [here](https://github.com/open-mmlab/mmcv#installation) for different versions of MMCV compatible to different PyTorch and CUDA versions.
+```shell
+pip install mmselfsup
+```
 
-   Optionally you can compile mmcv from source if you need to develop both mmcv and mmselfsup. Refer to the [guide](https://github.com/open-mmlab/mmcv#installation) for details.
+## Verify the installation
 
-   You can simply install MMClassification with the following command:
+To verify whether MMSelfSup is installed correctly, we can run the following sample code to initialize a model and inference a demo image.
 
-   ```shell
-   pip install mmcls
-   ```
+```python
+import torch
 
-2. Clone MMSelfSup repository and install
+from mmselfsup.models import build_algorithm
 
-   ```shell
-   git clone https://github.com/open-mmlab/mmselfsup.git
-   cd mmselfsup
-   pip install -v -e .
-   ```
+model_config = dict(
+    type='Classification',
+    backbone=dict(
+        type='ResNet',
+        depth=50,
+        in_channels=3,
+        num_stages=4,
+        strides=(1, 2, 2, 2),
+        dilations=(1, 1, 1, 1),
+        out_indices=[4],  # 0: conv-1, x: stage-x
+        norm_cfg=dict(type='BN'),
+        frozen_stages=-1),
+    head=dict(
+        type='ClsHead', with_avg_pool=True, in_channels=2048,
+        num_classes=1000))
 
-   **Note:**
+model = build_algorithm(model_config).cuda()
 
-   - When specifying `-e` or `develop`, MMSelfSup is installed on dev mode, any local modifications made to the code will take effect without reinstallation.
+image = torch.randn((1, 3, 224, 224)).cuda()
+label = torch.tensor([1]).cuda()
 
-3. Install MMSegmentation and MMDetection
+loss = model.forward_train(image, label)
+```
 
-   You can simply install MMSegmentation and MMDetection with the following command:
+The above code is supposed to run successfully upon you finish the installation.
 
-   ```shell
-   pip install mmsegmentation mmdet
-   ```
+## Customized installation
 
-   In addition to installing MMSegmentation and MMDetection by pip, user can also install them by [mim](https://github.com/open-mmlab/mim).
+### Benchmark
 
-   ```shell
-   pip install openmim
-   mim install mmdet
-   mim install mmsegmentation
-   ```
+The [Best Practices](#best-practices) is for basic usage, if you need to evaluate your pre-training model with some downstream tasks such as detection or segmentation, please also install [MMDetection](https://github.com/open-mmlab/mmdetection) and [MMSegmentation](https://github.com/open-mmlab/mmsegmentation).
 
-## A from-scratch setup script
+If you don't run MMDetection and MMSegmentation benchmark, it is unnecessary to install them.
 
-Here is a full script for setting up mmselfsup with conda.
+You can simply install MMDetection and MMSegmentation with the following command:
 
 ```shell
-conda create -n openmmlab python=3.7 -y
-conda activate openmmlab
+pip install mmdet mmsegmentation
+```
 
-conda install -c pytorch pytorch torchvision -y
+For more details, you can check the installation page of [MMDetection](https://github.com/open-mmlab/mmdetection/blob/master/docs/en/get_started.md) and [MMSegmentation](https://github.com/open-mmlab/mmsegmentation/blob/master/docs/en/get_started.md).
 
-# install the latest mmcv
-pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html
+### CUDA versions
 
-# install mmdetection mmsegmentation
-pip install mmsegmentation mmdet
+When installing PyTorch, you need to specify the version of CUDA. If you are not clear on which to choose, follow our recommendations:
 
-git clone https://github.com/open-mmlab/mmselfsup.git
-cd mmselfsup
-pip install -v -e .
+- For Ampere-based NVIDIA GPUs, such as GeForce 30 series and NVIDIA A100, CUDA 11 is a must.
+- For older NVIDIA GPUs, CUDA 11 is backward compatible, but CUDA 10.2 offers better compatibility and is more lightweight.
+
+Please make sure the GPU driver satisfies the minimum version requirements. See [this table](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions) for more information.
+
+```{note}
+Installing CUDA runtime libraries is enough if you follow our best practices, because no CUDA code will be compiled locally. However if you hope to compile MMCV from source or develop other CUDA operators, you need to install the complete CUDA toolkit from NVIDIA's [website](https://developer.nvidia.com/cuda-downloads), and its version should match the CUDA version of PyTorch. i.e., the specified version of cudatoolkit in `conda install` command.
+```
+
+### Install MMCV without MIM
+
+MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex way. MIM solves such dependencies automatically and makes the installation easier. However, it is not a must.
+
+To install MMCV with pip instead of MIM, please follow [MMCV installation guides](https://mmcv.readthedocs.io/en/latest/get_started/installation.html). 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.
+
+```shell
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
 ```
 
-## Another option: Docker Image
+### Another option: Docker Image
 
 We provide a [Dockerfile](/docker/Dockerfile) to build an image.
 
@@ -147,42 +156,44 @@ docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/workspace/mmselfsup/data
 
 `{DATA_DIR}` is your local folder containing all these datasets.
 
-## Verification
+### Install on Google Colab
 
-To verify whether MMSelfSup is installed correctly, we can run the following sample code to initialize a model and inference a demo image.
+[Google Colab](https://research.google.com/) usually has PyTorch installed,
+thus we only need to install MMCV and MMSeflSup with the following commands.
 
-```py
-import torch
+**Step 0.** Install [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
 
-from mmselfsup.models import build_algorithm
+```shell
+!pip3 install openmim
+!mim install mmcv-full
+```
 
-model_config = dict(
-    type='Classification',
-    backbone=dict(
-        type='ResNet',
-        depth=50,
-        in_channels=3,
-        num_stages=4,
-        strides=(1, 2, 2, 2),
-        dilations=(1, 1, 1, 1),
-        out_indices=[4],  # 0: conv-1, x: stage-x
-        norm_cfg=dict(type='BN'),
-        frozen_stages=-1),
-    head=dict(
-        type='ClsHead', with_avg_pool=True, in_channels=2048,
-        num_classes=1000))
+**Step 1.** Install MMSelfSup from the source.
 
-model = build_algorithm(model_config).cuda()
+```shell
+!git clone https://github.com/open-mmlab/mmselfsup.git
+%cd mmselfsup
+!pip install -e .
+```
 
-image = torch.randn((1, 3, 224, 224)).cuda()
-label = torch.tensor([1]).cuda()
+**Step 2.** Verification.
 
-loss = model.forward_train(image, label)
+```python
+import mmselfsup
+print(mmselfsup.__version__)
+# Example output: 0.9.0
 ```
 
-The above code is supposed to run successfully upon you finish the installation.
+```{note}
+Within Jupyter, the exclamation mark `!` is used to call external executables and `%cd` is a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) to change the current working directory of Python.
+```
+
+## Trouble shooting
+
+If you have some issues during the installation, please first view the [FAQ](faq.md) page.
+You may [open an issue](https://github.com/open-mmlab/mmselfsup/issues/new/choose) on GitHub if no solution is found.
 
-## Using multiple MMSelfSup versions
+# Using multiple MMSelfSup versions
 
 If there are more than one mmselfsup on your machine, and you want to use them alternatively, the recommended way is to create multiple conda environments and use different environments for different versions.
 

diff --git a/docs/zh_cn/faq.md b/docs/zh_cn/faq.md
@@ -0,0 +1,20 @@
+# 常见问题解答
+
+我们在这里列出了使用时的一些常见问题及其相应的解决方案。 如果您发现有一些问题被遗漏，请随时提 PR 丰富这个列表。 如果您无法在此获得帮助，请使用 [issue 模板](https://github.com/open-mmlab/mmselfsup/tree/master/.github/ISSUE_TEMPLATE)创建问题，但是请在模板中填写所有必填信息，这有助于我们更快定位问题。
+
+## 安装相关
+
+下表显示了与 MMSelfSup 适配的 MMCV, MMClassification, MMDetection 和 MMSegmentation 的版本号。 为避免安装过程中出现问题，请参照下表安装适配的版本。
+
+| MMSelfSup version |    MMCV version     |  MMClassification version   | MMSegmentation version | MMDetection version |
+| :---------------: | :-----------------: | :-------------------------: | :--------------------: | :-----------------: |
+|  0.9.0 (master)   | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.19.0   |
+|       0.8.0       | mmcv-full >= 1.4.2  |       mmcls >= 0.21.0       |    mmseg >= 0.20.2     |   mmdet >= 2.19.0   |
+|       0.7.1       | mmcv-full >= 1.3.16 | mmcls >= 0.19.0, \<= 0.20.1 |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+|       0.6.0       | mmcv-full >= 1.3.16 |       mmcls >= 0.19.0       |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+|       0.5.0       | mmcv-full >= 1.3.16 |              /              |    mmseg >= 0.20.2     |   mmdet >= 2.16.0   |
+
+**注意:**
+
+- 如果您已经安装了 mmcv, 您需要运行 `pip uninstall mmcv` 来卸载已经安装的 mmcv。 如果您在本地同时安装了 mmcv 和 mmcv-full, `ModuleNotFoundError` 将会抛出。
+- 如过您仍然对版本问题有疑问，欢迎创建 issue 并提供您的依赖库信息。