Skip to content

GitLab

Switch branch/tag
Find file Normal viewHistoryPermalink
installation.md 11.8 KB
Newer Older
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
1
2
3
4 
## Installation

There are two versions of MMCV:
Zaida Zhou's avatar
Rename mmcv package name (#2235)  
Zaida Zhou committed
5
6 
- **mmcv**: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build.
- **mmcv-lite**: lite, without CUDA ops but all other features, similar to mmcv\<1.0.0. It is useful when you do not need those CUDA ops.
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
7
Zaida Zhou's avatar
[Docs] Use myst parser (#1287)  
Zaida Zhou committed
8 
```{warning}
Zaida Zhou's avatar
Add code spell hook to pre-commit and fix typos (#1384)  
Zaida Zhou committed
9 
Do not install both versions in the same environment, otherwise you may encounter errors like `ModuleNotFound`. You need to uninstall one before installing the other. `Installing the full version is highly recommended if CUDA is avaliable`.
Zaida Zhou's avatar
[Docs] Use myst parser (#1287)  
Zaida Zhou committed
10 
```
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
11
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
12 
### Install mmcv
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
13
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
14
15
16 
```{note}
The following installation steps are for Linux and Windows platforms only. To install mmcv on macOS platform, please refer to [build mmcv from source](build.md#build-on-macos).
```
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
17
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
18 
Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [PyTorch official installation guide](https://pytorch.org/get-started/locally/#start-locally). This can be verified using the following command
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
19
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
20
21
22 
```bash
python -c 'import torch;print(torch.__version__)'
```
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
23
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
24 
If version information is output, then PyTorch is installed.
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
25
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
26 
#### Install with mim (recommended)
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
27
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
28 
[mim](https://github.com/open-mmlab/mim) is the package management tool for the OpenMMLab projects, which makes it easy to install mmcv
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
29
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
30
31 
```bash
pip install -U openmim
LYMDLUT's avatar
[Docs] Make installation commands compatible with windows cmd (#2353)  
LYMDLUT committed
32 
mim install "mmcv>=2.0.0rc1"
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
33
34 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51 
If you find that the above installation command does not use a pre-built package ending with `.whl` but a source package ending with `.tar.gz`, you may not have a pre-build package corresponding to the PyTorch or CUDA or mmcv version, in which case you can [build mmcv from source](build.md).

<details>
<summary>Installation log using pre-built packages</summary>

Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv<br />
<b>Downloading https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/mmcv-2.0.0rc1-cp38-cp38-manylinux1_x86_64.whl</b>

</details>

<details>
<summary>Installation log using source packages</summary>

Looking in links: https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html<br />
Collecting mmcv==2.0.0rc1<br />
<b>Downloading mmcv-2.0.0rc1.tar.gz</b>
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
52
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
53 
</details>
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
54
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
55 
To install a specific version of mmcv, for example, mmcv version 2.0.0rc1, you can use the following command
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
56
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
57
58 
```bash
mim install mmcv==2.0.0rc1
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
59
60 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
61
62
63
64 
:::{note}
If you would like to use `opencv-python-headless` instead of `opencv-python`,
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
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
65
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
66
67
68 
Alternatively, if it takes too long to install a dependency library, you can specify the pypi source

```bash
LYMDLUT's avatar
[Docs] Make installation commands compatible with windows cmd (#2353)  
LYMDLUT committed
69 
mim install "mmcv>=2.0.0rc1" -i https://pypi.tuna.tsinghua.edu.cn/simple
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
70
71 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284 
:::

You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/2.x/.dev_scripts/check_installation.py) to check the installation of mmcv-full after running the installation commands.

#### Install with pip

Use the following command to check the version of CUDA and PyTorch

```bash
python -c 'import torch;print(torch.__version__);print(torch.version.cuda)'
```

Select the appropriate installation command depending on the type of system, CUDA version, PyTorch version, and MMCV version

<html>
<body>
    <style>
      select {
          z-index: 1000;
          position: absolute;
          top: 10px;
          width: 6.7rem;
      }
      #select-container {
          position: relative;
          height: 30px;
      }
      #select-cmd {
          background-color: #f5f6f7;
          font-size: 14px;
          margin-top: 20px;
      }
      /* 让每一个都间隔1.3rem */
      #select-os {
          /* left: 1.375rem; */
          left: 0;
      }
      #select-cuda {
          /* left: 9.375rem;    9.375 = 1.375 + 6.7 + 1.3 */
          left: 8rem;
      }
      #select-torch {
          /* left: 17.375rem;    17.375 = 9.375 + 6.7 + 1.3 */
          left: 16rem;
      }
      #select-mmcv {
          /* left: 25.375rem;    25.375 = 17.375 + 6.7 + 1.3 */
          left: 24rem;
      }
    </style>
    <div id="select-container">
        <select
            onmousedown="handleSelectMouseDown(this.id)"
            onblur="handleSelectBlur(this.id)"
            onchange="changeOS(this.value)"
            id="select-os">
        </select>
        <select
            onmousedown="handleSelectMouseDown(this.id)"
            onblur="handleSelectBlur(this.id)"
            onchange="changeCUDA(this.value)"
            id="select-cuda">
        </select>
        <select
            onmousedown="handleSelectMouseDown(this.id)"
            onblur="handleSelectBlur(this.id)"
            onchange="changeTorch(this.value)"
            id="select-torch">
        </select>
        <select
            onmousedown="handleSelectMouseDown(this.id)"
            onblur="handleSelectBlur(this.id)"
            onchange="changeMMCV(this.value)"
            id="select-mmcv">
        </select>
    </div>
    <pre id="select-cmd"></pre>
</body>
<script>
    let osVal, cudaVal, torchVal, mmcvVal;
    function changeMMCV(val) {
        mmcvVal = val;
        change("select-mmcv");
    }
    function changeTorch(val) {
        torchVal = val;
        change("select-torch");
    }
    function changeCUDA(val) {
        cudaVal = val;
        change("select-cuda");
    }
    function changeOS(val) {
        osVal = val;
        change("select-os");
    }
    function handleSelectMouseDown(id) {
        const dom = document.getElementById(id);
        if (!dom) return;
        const len = dom?.options?.length;
        if (len >= 9) {
            dom.size = 10;
            dom.style.zIndex = 100;
        }
    }
    function handleSelectClick() {
        const selects = Array.from(document.getElementsByTagName("select"));
        selects.forEach(select => {
            select.size = 1;
        });
    }
    function handleSelectBlur(id) {
        const dom = document.getElementById(id);
        if (!dom) {
            handleSelectClick();
            return;
        }
        dom.size = 1;
        dom.style.zIndex = 1;
    }
    function changeCmd() {
        const cmd = document.getElementById("select-cmd");
        let cmdString = "pip install mmcv=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html";
        // e.g: pip install mmcv==2.0.0rc1 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9/index.html
        const cudaVersion = `${cudaVal === "cpu" ? cudaVal : `cu${cudaVal.split(".").join("")}`}`;
        const torchVersion = `torch${torchVal.substring(0, torchVal.length - 2)}`;
        cmdString = cmdString.replace("{cu_version}", cudaVersion).replace("{mmcv_version}", mmcvVal).replace("{torch_version}", torchVersion);
        cmd.textContent = cmdString;
    }
    function unique(arr) {
        if (!arr || !Array.isArray(arr)) return [];
        return [...new Set(arr)];
    }
    function genOptionFragment(data, id) {
        const name = id.includes("-")? id.split("-")[1] : id;
        const fragment = new DocumentFragment();
        data.forEach(option => {
            const ele = document.createElement("option");
            let text = `${name} ${option}`;
            if (name === "os" || option.toUpperCase() === "CPU") {
                text = `${option}`;
            }
            ele.textContent = text;
            ele.value = option;
            ele.addEventListener('click', handleSelectClick);
            fragment.appendChild(ele);
        });
        return fragment;
    }
    function findAndAppend(data, id) {
        const fragment = genOptionFragment(data, id);
        const dom = document.getElementById(id);
        if (dom) dom.replaceChildren(fragment);
    }
    function change(id) {
        const order = ["select-mmcv", "select-torch", "select-cuda", "select-os"];
        const idx = order.indexOf(id);
        if (idx === -1) return;
        const versionDetail = version[osVal];
        if (idx >= 3) {
            let cuda = [];
            versionDetail.forEach(v => {
                cuda.push(v.cuda);
            });
            cuda = unique(cuda);
            cudaVal = cuda[0];
            findAndAppend(cuda, "select-cuda");
        }
        if (idx >= 2) {
            const torch = [];
            versionDetail.forEach(v => {
                if (v.cuda === cudaVal) torch.push(v.torch);
            });
            torchVal = torch[0];
            findAndAppend(torch, "select-torch");
        }
        if (idx >= 1) {
            let mmcv = [];
            versionDetail.forEach(v => {
                if (v.cuda === cudaVal && v.torch === torchVal) mmcv = v.mmcv;
            });
            mmcvVal = mmcv[0];
            findAndAppend(mmcv, "select-mmcv");
        }
        changeCmd();
    }
    function init() {
        document.addEventListener("click", handleSelectBlur);
        const version = window.version;
        const os = Object.keys(version);
        osVal = os[0];
        findAndAppend(os, "select-os");
        change("select-os");
        changeCmd();
    }
    window.onload = function () {
        const url = "../_static/version.json"
        const request = new XMLHttpRequest();
        request.open("get", url);
        request.send(null);
        request.onload = function () {
            if (request.status !== 200) return;
            const data = JSON.parse(request.responseText);
            window.version = data;
            init();
        }
    }
</script>
</html>

If you do not find a corresponding version in the dropdown box above, you probably do not have a pre-built package corresponding to the PyTorch or CUDA or mmcv version, at which point you can [build mmcv from source](build.md).

:::{note}
Zaida Zhou's avatar
Rename mmcv package name (#2235)  
Zaida Zhou committed
285 
mmcv is only compiled on PyTorch 1.x.0 because the compatibility
Zaida Zhou's avatar
Polish readme (#1320)  
Zaida Zhou committed
286 
usually holds between 1.x.0 and 1.x.1. If your PyTorch version is 1.x.1, you
Zaida Zhou's avatar
Rename mmcv package name (#2235)  
Zaida Zhou committed
287 
can install mmcv compiled with PyTorch 1.x.0 and it usually works well.
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
288
289
290
291
292
293
294 
For example, if your PyTorch version is 1.8.1, you can feel free to choose 1.8.x.
:::

:::{note}
If you would like to use `opencv-python-headless` instead of `opencv-python`,
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
Polish readme (#1320)  
Zaida Zhou committed
295
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
296
297
298 
Alternatively, if it takes too long to install a dependency library, you can specify the pypi source

```bash
LYMDLUT's avatar
[Docs] Make installation commands compatible with windows cmd (#2353)  
LYMDLUT committed
299 
mim install "mmcv>=2.0.0rc1" -i https://pypi.tuna.tsinghua.edu.cn/simple
Zaida Zhou's avatar
Polish readme (#1320)  
Zaida Zhou committed
300
301 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
302 
:::
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
303
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
304
305
306
307
308
309
310
311
312 
You can run [check_installation.py](https://github.com/open-mmlab/mmcv/blob/2.x/.dev_scripts/check_installation.py) to check the installation of mmcv after running the installation commands.

#### Using mmcv with Docker

Build with local repository

```bash
git clone https://github.com/open-mmlab/mmcv.git && cd mmcv
docker build -t mmcv -f docker/release/Dockerfile .
Zaida Zhou's avatar
[Docs] Add more Windows information in README (#1829)  
Zaida Zhou committed
313
314 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
315 
Or build with remote repository
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
316
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
317
318 
```bash
docker build -t mmcv https://github.com/open-mmlab/mmcv.git#2.x:docker/release
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
319
320 
```
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
321 
The [Dockerfile](release/Dockerfile) installs latest released version of mmcv-full by default, but you can specify mmcv versions to install expected versions.
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
322
Zaida Zhou's avatar
[Docs] Refine reamde and installation (#2340)  
Zaida Zhou committed
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343 
```bash
docker image build -t mmcv -f docker/release/Dockerfile --build-arg MMCV=2.0.0rc1 .
```

If you also want to use other versions of PyTorch and CUDA, you can also pass them when building docker images.

An example to build an image with PyTorch 1.11 and CUDA 11.3.

```bash
docker build -t mmcv -f docker/release/Dockerfile \
    --build-arg PYTORCH=1.11.0 \
    --build-arg CUDA=11.3 \
    --build-arg CUDNN=8 \
    --build-arg MMCV=2.0.0rc1 .
```

More available versions of PyTorch and CUDA can be found at [dockerhub/pytorch](https://hub.docker.com/r/pytorch/pytorch/tags).

### Install mmcv-lite

If you need to use PyTorch-related modules, make sure PyTorch has been successfully installed in your environment by referring to the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
344
345 

```python
Zaida Zhou's avatar
Rename mmcv package name (#2235)  
Zaida Zhou committed
346 
pip install mmcv-lite
Zaida Zhou's avatar
[Docs] Refactor docs (#1102)  
Zaida Zhou committed
347 
```