Skip to content

Commit 2d7baac

Browse files
wangruohuiwangruohui
authored
[Doc] Move wiki/installation to docs (open-mmlab#883)
1 parent 3351cdc commit 2d7baac

File tree

7 files changed

+194
-164
lines changed

7 files changed

+194
-164
lines changed

‎README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -97,21 +97,21 @@ Install PyTorch following [official instructions](https://pytorch.org/get-starte
9797
**Step 2.**
9898
Install MMCV with [MIM](https://github.com/open-mmlab/mim).
9999

100-
```
100+
```shell
101101
pip3 install openmim
102102
mim install mmcv-full
103103
```
104104

105105
**Step 3.**
106106
Install MMEditing from source.
107107

108-
```
108+
```shell
109109
git clone https://github.com/open-mmlab/mmediting.git
110110
cd mmediting
111111
pip3 install -e .
112112
```
113113

114-
Please refer to [install.md](../../wiki/1.-Installation) for more detailed instruction.
114+
Please refer to [install.md](docs/en/install.md) for more detailed instruction.
115115

116116
## Getting Started
117117

‎docker/README.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@ Run it with
1313
docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmediting/data mmediting
1414
```
1515

16-
**Note**
17-
18-
Versions defined in this [Dockerfile](Dockerfile) is not up-to-dated.
19-
If you use this Dockerfile in your project, you probably want to make some update.
20-
Feel free to submit a issue or PR for the update.
16+
**Note**:
17+
Versions defined in this [Dockerfile](Dockerfile) is not up-to-date.
18+
If you use this Dockerfile in your project, you probably want to make some updates.
19+
Feel free to submit an issue or PR for the update.

‎docs/en/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Documentation
2727
:maxdepth: 2
2828
:caption: Get Started
2929

30-
install.rst
30+
install.md
3131
demo.md
3232

3333
.. toctree::

‎docs/en/install.md

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Installation
2+
3+
We highly recommend developers follow our best practices to install MMEditing.
4+
However, the whole process is highly customizable.
5+
See [Customize Installation](#customize-installation) section for more information.
6+
7+
## Best Practices
8+
9+
The following steps work on Linux, Windows, and macOS.
10+
If you have already set up a PyTorch environment, no matter using conda or pip, you can start from **step 3**.
11+
12+
**Step 0.**
13+
Download and install Miniconda from [official website](https://docs.conda.io/en/latest/miniconda.html).
14+
15+
**Step 1.**
16+
Create a [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html#) and activate it
17+
18+
```shell
19+
conda create --name mmedit python=3.8 -y
20+
conda activate mmedit
21+
```
22+
23+
**Step 2.**
24+
Install PyTorch following [official instructions](https://pytorch.org/get-started/locally/), e.g.
25+
26+
- On GPU platforms:
27+
28+
```shell
29+
conda install pytorch=1.10 torchvision cudatoolkit=11.3 -c pytorch
30+
```
31+
32+
- On CPU platforms:
33+
34+
```shell
35+
conda install pytorch=1.10 torchvision cpuonly -c pytorch
36+
```
37+
38+
**Step 3.**
39+
Install pre-built [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
40+
41+
```shell
42+
pip3 install openmim
43+
mim install mmcv-full==1.5.0
44+
```
45+
46+
**Step 4.**
47+
Install [MMEditing](https://github.com/open-mmlab/mmediting) from the source code.
48+
49+
```shell
50+
git clone https://github.com/open-mmlab/mmediting.git
51+
cd mmediting
52+
pip3 install -e .
53+
```
54+
55+
**Step 5.**
56+
Verification.
57+
58+
```shell
59+
cd ~
60+
python -c "import mmedit; print(mmedit.__version__)"
61+
# Example output: 0.14.0
62+
```
63+
64+
The installation is successful if the version number is output correctly.
65+
66+
## Customize Installation
67+
68+
### Version of Dependencies
69+
70+
You may change the version of Python, PyTorch, and MMCV by changing the version numbers in **Step 1, 2, and 3**, respectively.
71+
72+
Currently, MMEditing works with
73+
74+
- Python >= 3.6
75+
- [PyTorch](https://pytorch.org/) >= 1.5
76+
- [MMCV](https://github.com/open-mmlab/mmcv) >= 1.3.13
77+
78+
### Version of CUDA
79+
80+
When installing PyTorch in **Step 2**, you need to specify the version of CUDA.
81+
If you are not clear on which to choose, follow our recommendations:
82+
83+
1. For Ampere-based NVIDIA GPUs, such as GeForce 30 series and NVIDIA A100, **CUDA 11 is a must**.
84+
2. For older NVIDIA GPUs, CUDA 11 is backward compatible, but CUDA 10.2 offers better compatibility and is more lightweight.
85+
86+
Please also make sure the GPU driver satisfies the minimum version requirements.
87+
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.
88+
89+
Please **Note** that there is no need to install the complete CUDA toolkit if you follow our [best practices](#best-practices) because no CUDA code will be compiled.
90+
However, if you hope to compile MMCV or other C++/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**, which is the version of `cudatoolkit` in `conda install`.
91+
92+
### Install without Conda
93+
94+
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,
95+
96+
```shell
97+
pip3 install torch torchvision
98+
```
99+
100+
However, an `--extra-index-url` or `-f` option is usually required to specify the CPU / CUDA version.
101+
See [PyTorch website](https://pytorch.org/get-started/locally/) for more details.
102+
103+
### Install without MIM
104+
105+
[MMCV](https://github.com/open-mmlab/mmcv) contains C++ and CUDA extensions, thus depending on PyTorch in a complex way.
106+
[MIM](https://github.com/open-mmlab/mim) solves such dependency automatically and makes installation easier.
107+
However, it is not a must.
108+
109+
To install MMCV with `pip` instead of MIM, please follow [MMCV installation guides](https://mmcv.readthedocs.io/en/latest/get_started/installation.html).
110+
This requires manually specifying a *find-url* based on PyTorch version and its CUDA version.
111+
112+
For example, the following command install `mmcv-full` built for PyTorch 1.10.x and CUDA 11.3.
113+
114+
```shell
115+
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html
116+
```
117+
118+
### On macOS
119+
120+
Pre-built MMCV package is not available for macOS, so you have to build MMCV from the source.
121+
Pip will build it automatically during installation, but it requires a C++ compiler.
122+
A simple solution is to install Clang with `xcode-select --install`.
123+
124+
Under such circumstances, MIM is not required and `pip install mmcv-full -v` can do the job.
125+
See [MMCV installation guides](https://mmcv.readthedocs.io/en/latest/get_started/build.html) for more details.
126+
127+
### On Google Colab
128+
129+
Online machine learning platform such as [Google Colab](https://research.google.com/) usually has PyTorch installed.
130+
Thus we only need to install MMCV and MMEditing with the following commands.
131+
132+
**Step 1.**
133+
Install pre-built [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
134+
135+
```ipython
136+
!pip3 install openmim
137+
!mim install mmcv-full
138+
```
139+
140+
**Step 2.**
141+
Install MMEditing from the source.
142+
143+
```ipython
144+
!git clone https://github.com/open-mmlab/mmediting.git
145+
%cd mmediting
146+
!pip3 install -e .
147+
```
148+
149+
**Step 3.**
150+
Verification.
151+
152+
```python
153+
import mmedit
154+
print(mmedit.__version__)
155+
# Example output: 0.13.0
156+
```
157+
158+
**Note**: within Jupyter, the exclamation mark `!` is used to call external executables and `%cd` is a [IPython magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) to change the current working directory of Python.
159+
160+
## Additional Notes
161+
162+
### Speed up Installation with Mirror
163+
164+
One can configure conda and pip mirrors to speed up the installation.
165+
This step is very practical for users geologically in China.
166+
167+
See the below links (in Chinese) for details：
168+
169+
- <https://mirrors.tuna.tsinghua.edu.cn/help/pypi/>
170+
- <https://mirror.tuna.tsinghua.edu.cn/help/anaconda/>
171+
- <https://developer.aliyun.com/mirror/pypi>
172+
173+
### On `-e .`
174+
175+
You may be curious about what `-e .` means when supplied with `pip install`.
176+
Here is the description:
177+
178+
- `-e` means [editable mode](https://pip.pypa.io/en/latest/cli/pip_install/#cmdoption-e). When `import mmedit`, modules under the cloned directory are imported. If `pip install` without `-e`, pip will copy cloned codes to somewhere like `lib/python/site-package`. Consequently, modified code under the cloned directory takes no effect unless `pip install` again. This is particularly convenient for developers. If some codes are modified, new codes will be imported next time without reinstallation.
179+
- `.` means code in this directory
180+
181+
You can also use `pip -e .[all]`, which will install more dependencies, especially for pre-commit hooks and unittests.

‎docs/en/old/install.md

-155
This file was deleted.

‎docs/en/install.rst ‎docs/en/old/install.rst

File renamed without changes.

‎docs/zh_cn/install.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
```{warning}
2+
中文版本的安装文档过于陈旧，请参考英文版本。
3+
如果您希望帮助翻译英文版安装文档，请通过issue联系我们
4+
```
5+
16
## 依赖
27

38
- Linux / Windows / Mac

0 commit comments

Comments
 (0)