build.md 7.13 KB
Newer Older
WRH's avatar
WRH committed
1
2
3
4
5
6
7
8
9
10
11
## Build MMCV from source

### Build on Linux or macOS

After cloning the repo with

```bash
git clone https://github.com/open-mmlab/mmcv.git
cd mmcv
```

12
13
14
15
16
17
It is recommended to install `ninja` to speed up the compilation

```bash
pip install -r requirements/optional.txt
```

WRH's avatar
WRH committed
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
You can either

- install the lite version

  ```bash
  pip install -e .
  ```

- install the full version

  ```bash
  MMCV_WITH_OPS=1 pip install -e .
  ```

If you are on macOS, add the following environment variables before the installing command.

```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++'
```

e.g.,

```bash
CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
```

Zaida Zhou's avatar
Zaida Zhou committed
44
45
```{note}
If you would like to use `opencv-python-headless` instead of `opencv-python`,
WRH's avatar
WRH committed
46
47
e.g., in a minimum container environment or servers without GUI,
you can first install it before installing MMCV to skip the installation of `opencv-python`.
Zaida Zhou's avatar
Zaida Zhou committed
48
```
WRH's avatar
WRH committed
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
### Build on Windows

Building MMCV on Windows is a bit more complicated than that on Linux.
The following instructions show how to get this accomplished.

#### Prerequisite

The following software is required for building MMCV on windows.
Install them first.

- [Git](https://git-scm.com/download/win)
  - During installation, tick **add git to Path**.
- [Visual Studio Community 2019](https://visualstudio.microsoft.com)
  - A compiler for C++ and CUDA codes.
- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
  - Official distributions of Python should work too.
- [CUDA 10.2](https://developer.nvidia.com/cuda-10.2-download-archive)
  - Not required for building CPU version.
  - Customize the installation if necessary. As a recommendation, skip the driver installation if a newer version is already installed.

69
70
71
```{note}
You should know how to set up environment variables, especially `Path`, on Windows. The following instruction relies heavily on this skill.
```
WRH's avatar
WRH committed
72
73
74
75
76
77
78

#### Setup Python Environment

1. Launch Anaconda prompt from Windows Start menu

    Do not use raw `cmd.exe` s instruction is based on PowerShell syntax.

79
2. Create a new conda environment
WRH's avatar
WRH committed
80
81
82
83
84
85

    ```shell
    conda create --name mmcv python=3.7  # 3.6, 3.7, 3.8 should work too as tested
    conda activate mmcv  # make sure to activate environment before any operation
    ```

86
3. Install PyTorch. Choose a version based on your need.
WRH's avatar
WRH committed
87
88
89
90
91
92
93

    ```shell
    conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
    ```

    We only tested PyTorch version >= 1.6.0.

94
4. Prepare MMCV source code
WRH's avatar
WRH committed
95
96
97
98
99
100

    ```shell
    git clone https://github.com/open-mmlab/mmcv.git
    cd mmcv
    ```

101
5. Install required Python packages
WRH's avatar
WRH committed
102
103

    ```shell
104
105
106
107
108
109
110
    pip3 install -r requirements/runtime.txt
    ```

6. It is recommended to install `ninja` to speed up the compilation

    ```bash
    pip install -r requirements/optional.txt
WRH's avatar
WRH committed
111
112
113
114
115
116
117
118
    ```

#### Build and install MMCV

MMCV can be built in three ways:

1. Lite version (without ops)

119
   In this way, no custom ops are compiled and mmcv is a pure python package.
WRH's avatar
WRH committed
120

121
2. Full version (CPU ops)
WRH's avatar
WRH committed
122

123
   Module `ops` will be compiled as a pytorch extension, but only x86 code will be compiled. The compiled ops can be executed on CPU only.
WRH's avatar
WRH committed
124

125
3. Full version (CUDA ops)
WRH's avatar
WRH committed
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

   Both x86 and CUDA codes of `ops` module will be compiled. The compiled version can be run on both CPU and CUDA-enabled GPU (if implemented).

##### Common steps

1. Set up MSVC compiler

    Set Environment variable, add `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.27.29110\bin\Hostx86\x64` to `PATH`, so that `cl.exe` will be available in prompt, as shown below.

    ```none
    (base) PS C:\Users\xxx> cl
    Microsoft (R) C/C++ Optimizing  Compiler Version 19.27.29111 for x64
    Copyright (C) Microsoft Corporation.   All rights reserved.

    usage: cl [ option... ] filename... [ / link linkoption... ]
    ```

    For compatibility, we use the x86-hosted and x64-targeted compiler. note `Hostx86\x64` in the path.

    You may want to change the system language to English because pytorch will parse text output from `cl.exe` to check its version. However only utf-8 is recognized. Navigate to Control Panel -> Region -> Administrative -> Language for Non-Unicode programs and change it to English.

##### Option 1: Build MMCV (lite version)

After finishing above common steps, launch Anaconda shell from Start menu and issue the following commands:

```shell
# activate environment
conda activate mmcv
# change directory
cd mmcv
# install
python setup.py develop
# check
pip list
```

##### Option 2: Build MMCV (full version with CPU)

1. Finish above common steps
165
2. Set up environment variables
WRH's avatar
WRH committed
166
167
168
169
170
171

    ```shell
    $env:MMCV_WITH_OPS = 1
    $env:MAX_JOBS = 8  # based on your available number of CPU cores and amount of memory
    ```

172
3. Following build steps of the lite version
WRH's avatar
WRH committed
173
174
175
176
177
178
179

    ```shell
    # activate environment
    conda activate mmcv
    # change directory
    cd mmcv
    # build
180
    python setup.py build_ext # if success, cl will be launched to compile ops
WRH's avatar
WRH committed
181
182
183
184
185
186
187
188
189
    # install
    python setup.py develop
    # check
    pip list
    ```

##### Option 3: Build MMCV (full version with CUDA)

1. Finish above common steps
190
2. Make sure `CUDA_PATH` or `CUDA_HOME` is already set in `envs` via `ls env:`, desired output is shown as below:
WRH's avatar
WRH committed
191
192
193
194
195
196
197
198
199
200
201
202
203

   ```none
   (base) PS C:\Users\WRH> ls env:

   Name                           Value
   ----                           -----
   <... omit some lines ...>
   CUDA_PATH                      C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
   CUDA_PATH_V10_1                C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.1
   CUDA_PATH_V10_2                C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
   <... omit some lines ...>
   ```

204
   This should already be done by CUDA installer. If not, or you have multiple version of CUDA toolkit installed, set it with
WRH's avatar
WRH committed
205
206
207
208
209
210
211

   ```shell
   $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
   # OR
   $env:CUDA_HOME = $env:CUDA_PATH_V10_2 # if CUDA_PATH_V10_2 is in envs:
   ```

212
3. Set CUDA target arch
WRH's avatar
WRH committed
213
214
215
216

   ```shell
   # Suppose you are using GTX 1080, which is of capability 6.1
   $env:TORCH_CUDA_ARCH_LIST="6.1"
217
   # OR build all supported arch, will be slow
WRH's avatar
WRH committed
218
219
220
   $env:TORCH_CUDA_ARCH_LIST="3.5 3.7 5.0 5.2 6.0 6.1 7.0 7.5"
   ```

Zaida Zhou's avatar
Zaida Zhou committed
221
222
223
```{note}
Check your the compute capability of your GPU from [here](https://developer.nvidia.com/cuda-gpus).
```
WRH's avatar
WRH committed
224

225
4. Launch compiling the same way as CPU
WRH's avatar
WRH committed
226
227
228
229
230
231
232
233
234

   ```shell
   $env:MMCV_WITH_OPS = 1
   $env:MAX_JOBS = 8  # based on available number of CPU cores and amount of memory
   # activate environment
   conda activate mmcv
   # change directory
   cd mmcv
   # build
235
   python setup.py build_ext # if success, cl will be launched to compile ops
WRH's avatar
WRH committed
236
237
238
239
240
241
   # install
   python setup.py develop
   # check
   pip list
   ```

242
243
244
```{note}
If you are compiling against PyTorch 1.6.0, you might meet some errors from PyTorch as described in [this issue](https://github.com/pytorch/pytorch/issues/42467). Follow [this pull request](https://github.com/pytorch/pytorch/pull/43380/files) to modify the source code in your local PyTorch installation.
```
WRH's avatar
WRH committed
245

246
If you meet issues when running or compiling mmcv, we list some common issues in [Frequently Asked Question](../faq.html).