|
1 | | -## `opencv-python-cuda` |
| 1 | +# opencv-python-cuda |
2 | 2 |
|
3 | | -Download: [Latest Release (4.12.0-dev1)](https://github.com/Breakthrough/opencv-python-cuda/releases/tag/4.12.0-dev1) |
| 3 | +**Pre-built NVIDIA® CUDA™ enabled OpenCV wheels for Python - batteries included.** |
4 | 4 |
|
5 | | -## What is `opencv-python-cuda`? |
| 5 | +[](https://github.com/Breakthrough/opencv-python-cuda/releases) |
| 6 | +[](https://github.com/Breakthrough/opencv-python-cuda/releases) |
| 7 | +[](#licensing) |
6 | 8 |
|
7 | | -Pre-built NVIDIA® CUDA™ enabled OpenCV packages for Python that come with all batteries included. This is a fork of [the official opencv-python project](https://github.com/opencv/opencv-python). Right now packages are only produced for Windows x64, and devices must be Maxwell class (GeForce 900 series) or newer. Once installed via `pip` (or another Python package manager like `uv`), the following should *just work*: |
| 9 | +This is a fork of the official [opencv-python](https://github.com/opencv/opencv-python) project that ships fully standalone CUDA-enabled OpenCV builds. No CUDA Toolkit, cuDNN, or other NVIDIA SDK needs to be installed - every required runtime library is bundled in the wheel, including hardware video decoding and encoding (NVDEC/NVENC). Once installed, the following should *just work*: |
8 | 10 |
|
9 | | -``` |
| 11 | +```python |
10 | 12 | import cv2 |
11 | 13 | print(cv2.cuda.getCudaEnabledDeviceCount()) |
12 | 14 | ``` |
13 | 15 |
|
14 | | -### Installation and Usage |
| 16 | +See the [project homepage](https://breakthrough.github.io/opencv-python-cuda/) for more documentation. |
15 | 17 |
|
16 | | -1. If you have previous/other manually installed (= not installed via ``pip``) version of OpenCV installed (e.g. cv2 module in the root of Python's site-packages), remove it before installation to avoid conflicts. |
17 | | -2. Make sure that your `pip` version is up-to-date (19.3 is the minimum supported version): `pip install --upgrade pip`. Check version with `pip -V`. For example Linux distributions ship usually with very old `pip` versions which cause a lot of unexpected problems especially with the `manylinux` format. |
18 | | -3. Download the latest build `opencv_python_cuda-*-win_amd64.whl` file and install it. |
19 | | -4. Import the `cv2` package as usual. |
| 18 | +## Requirements |
20 | 19 |
|
21 | | -Frequently Asked Questions |
22 | | --------------------------- |
| 20 | +- **Windows x64** (the only platform packages are currently produced for) |
| 21 | +- **NVIDIA GPU** - Maxwell class (GeForce GTX 900 series) or newer |
| 22 | +- **NVIDIA driver** - the wheel links directly against driver libraries, so an up-to-date driver must be installed for `import cv2` to succeed |
| 23 | +- **Python 3.7 or newer** - a single abi3 wheel covers all supported Python versions |
23 | 24 |
|
24 | | -Please refer to [the FAQ in the upstream project](https://github.com/opencv/opencv-python/?tab=readme-ov-file#frequently-asked-questions) for the most common questions. |
| 25 | +## Installation |
25 | 26 |
|
26 | | -**Q: How do I install `opencv-python-cuda`?** |
| 27 | +1. Download the latest `opencv_python_cuda-*-win_amd64.whl` from the [Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases). |
| 28 | +2. Install it with `pip` (or another package manager like `uv`): |
27 | 29 |
|
28 | | -A: Releases can be downloaded from [the Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases). You can download and install the pre-built Python .whl file with `pip install`. |
| 30 | + ``` |
| 31 | + pip install opencv_python_cuda-<version>-win_amd64.whl |
| 32 | + ``` |
29 | 33 |
|
30 | | -**Q: Can you upload `opencv-python-cuda` to PyPI?** |
| 34 | +3. Import the `cv2` package as usual. |
31 | 35 |
|
32 | | -A: No, the package is far too large and exceeds [project size limits](https://docs.pypi.org/project-management/storage-limits/). |
| 36 | +> [!NOTE] |
| 37 | +> If you have a previous manually-installed (not via `pip`) version of OpenCV (e.g. a `cv2` module in the root of Python's site-packages), remove it before installing to avoid conflicts. Also make sure your `pip` is up to date (19.3 is the minimum supported version): `pip install --upgrade pip`. |
33 | 38 |
|
34 | | -**Q: What do the wheels include?** |
| 39 | +## What's included |
35 | 40 |
|
36 | | -All OpenCV modules that can be enabled with CUDA. All required runtime files are included in the wheels. Non-free algorithms are excluded as per the following question. |
| 41 | +- All OpenCV modules that can be built with CUDA support |
| 42 | +- Hardware-accelerated video decoding and encoding via NVDEC/NVENC (`cv2.cudacodec`) |
| 43 | +- FFmpeg for video I/O |
| 44 | +- All required CUDA runtime libraries, bundled in the wheel |
37 | 45 |
|
38 | | -**Q: Why are non-free algorithms excluded?** |
| 46 | +Non-free algorithms (e.g. SURF) are excluded - see the FAQ below. |
| 47 | + |
| 48 | +## Documentation |
| 49 | + |
| 50 | +- [Project homepage](https://breakthrough.github.io/opencv-python-cuda/) - downloads and overview |
| 51 | +- [CUDA Compatibility Reference](https://breakthrough.github.io/opencv-python-cuda/cuda-compatibility.html) - GPU architectures, compute capabilities, and CUDA toolkit support |
| 52 | +- [Workflow Guide](https://breakthrough.github.io/opencv-python-cuda/workflow.html) - repository setup, triggering builds, and wheel size strategy |
| 53 | + |
| 54 | +## Frequently Asked Questions |
39 | 55 |
|
40 | | -A: Non-free algorithms such as SURF are not included in these packages because they are patented / non-free and therefore cannot be distributed as built binaries. Note that SIFT is included in the builds due to patent expiration since OpenCV versions 4.3.0 and 3.4.10. See this issue for more info: https://github.com/skvark/opencv-python/issues/126 |
| 56 | +For general OpenCV questions, refer to [the FAQ in the upstream project](https://github.com/opencv/opencv-python/?tab=readme-ov-file#frequently-asked-questions). |
41 | 57 |
|
42 | | -### Licensing |
| 58 | +**Q: Why can't I `pip install opencv-python-cuda` from PyPI?** |
43 | 59 |
|
44 | | -Opencv-python-cuda package (scripts in this repository) is available under MIT license. |
| 60 | +A: The package is far too large for PyPI and exceeds its [project size limits](https://docs.pypi.org/project-management/storage-limits/). Download wheels from the [Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases) instead. |
| 61 | + |
| 62 | +**Q: Why does `import cv2` fail with "DLL load failed"?** |
| 63 | + |
| 64 | +A: The wheel requires an NVIDIA driver to be installed. On machines without one (or with a very old driver), the bundled CUDA and video codec libraries cannot be loaded. |
| 65 | + |
| 66 | +**Q: Why are non-free algorithms excluded?** |
45 | 67 |
|
46 | | -OpenCV itself is available under [Apache 2](https://github.com/opencv/opencv/blob/master/LICENSE) license. |
| 68 | +A: Non-free algorithms such as SURF are patented and cannot be distributed as built binaries. Note that SIFT *is* included, due to patent expiration as of OpenCV 4.3.0 / 3.4.10. See [opencv-python#126](https://github.com/skvark/opencv-python/issues/126) for more info. |
47 | 69 |
|
48 | | -Third party package licenses are at [LICENSE-3RD-PARTY.txt](https://github.com/opencv/opencv-python/blob/master/LICENSE-3RD-PARTY.txt). |
| 70 | +## Licensing |
49 | 71 |
|
50 | | -All wheels are distributed with [FFmpeg](http://ffmpeg.org) licensed under the [LGPLv2.1](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html), and redistributable portions of the NVIDIA® CUDA™ SDK under the [NVIDIA Software License Agreement (EULA)](https://docs.nvidia.com/cuda/eula/index.html). |
| 72 | +The opencv-python-cuda package (i.e. the scripts in this repository) is available under the MIT license. |
51 | 73 |
|
52 | | -Non-headless Linux wheels ship with [Qt 5](http://doc.qt.io/qt-5/lgpl.html) licensed under the [LGPLv3](http://www.gnu.org/licenses/lgpl-3.0.html). |
| 74 | +- OpenCV itself is available under the [Apache 2](https://github.com/opencv/opencv/blob/master/LICENSE) license. |
| 75 | +- All wheels are distributed with [FFmpeg](http://ffmpeg.org), licensed under the [LGPLv2.1](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html), and redistributable portions of the NVIDIA® CUDA™ SDK under the [NVIDIA Software License Agreement (EULA)](https://docs.nvidia.com/cuda/eula/index.html). |
| 76 | +- The packages include other binaries as well; the full list of licenses can be found in [LICENSE-3RD-PARTY.txt](https://github.com/opencv/opencv-python/blob/master/LICENSE-3RD-PARTY.txt). |
53 | 77 |
|
54 | | -The packages include also other binaries. Full list of licenses can be found from [LICENSE-3RD-PARTY.txt](https://github.com/opencv/opencv-python/blob/master/LICENSE-3RD-PARTY.txt). |
| 78 | +By downloading and using the software, you agree to fully comply with the terms and conditions of the CUDA EULA. |
0 commit comments