Skip to content

Commit ec5d6c0

Browse files
committed
[docs] Update homepage for OpenCV 5.0 release
1 parent ac50fea commit ec5d6c0

7 files changed

Lines changed: 641 additions & 190 deletions

File tree

‎.github/workflows/publish-docs.yml‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,48 @@
11
name: Publish Docs
22

3+
# Deploys docs/ plus a generated PEP 503 package index (packages/) to the
4+
# gh-pages branch. The index lists wheel assets from GitHub Releases so users
5+
# can `pip install opencv-python-cuda --extra-index-url <site>/packages/`.
36
on:
7+
# Keep this file identical on 4.x-cuda and 5.x-cuda: release events run the
8+
# copy in the tagged commit, which can be on either branch.
49
push:
510
branches:
6-
- 4.x-cuda
11+
- 5.x-cuda
712
paths:
813
- 'docs/**.html'
914
- 'docs/**.css'
1015
- 'docs/**.js'
16+
- 'tools/gen_simple_index.py'
17+
- '.github/workflows/publish-docs.yml'
18+
release:
19+
# Regenerate the package index whenever a release is created, moved, or removed.
20+
types: [published, edited, deleted, unpublished, released, prereleased]
1121
workflow_dispatch:
1222

23+
permissions:
24+
contents: write
25+
1326
jobs:
1427
deploy:
1528
runs-on: ubuntu-latest
1629
steps:
1730
- name: Checkout
1831
uses: actions/checkout@v4
32+
with:
33+
# Release events check out the tagged commit; always deploy the docs
34+
# from the repository's default branch instead.
35+
ref: ${{ github.event.repository.default_branch }}
36+
37+
- name: Set up Python
38+
uses: actions/setup-python@v5
39+
with:
40+
python-version: '3.x'
41+
42+
- name: Generate package index
43+
env:
44+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
45+
run: python tools/gen_simple_index.py --out index-out
1946

2047
- name: Update gh-pages Branch
2148
shell: bash
@@ -24,10 +51,13 @@ jobs:
2451
git config --global user.email github-actions@github.com
2552
2653
cp -r docs docs-tmp
54+
cp -r index-out/packages docs-tmp/packages
2755
git fetch origin gh-pages
2856
git checkout gh-pages
57+
# Replace the generated index wholesale so removed releases disappear.
58+
rm -rf packages
2959
mv -f docs-tmp/* .
30-
git add *
60+
git add -A -- . ':!docs-tmp' ':!index-out'
3161
if git diff --cached --quiet; then
3262
echo "No changes to deploy."
3363
else

‎README.md‎

Lines changed: 80 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,106 @@
1-
## `opencv-python-cuda`
1+
# opencv-python-cuda
22

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&reg; CUDA&trade; enabled OpenCV wheels for Python - batteries included.**
44

5-
## What is `opencv-python-cuda`?
5+
[![Latest release](https://img.shields.io/github/v/release/Breakthrough/opencv-python-cuda?include_prereleases&label=release)](https://github.com/Breakthrough/opencv-python-cuda/releases)
6+
[![Platform](https://img.shields.io/badge/platform-Windows%20x64-blue)](https://github.com/Breakthrough/opencv-python-cuda/releases)
7+
[![License](https://img.shields.io/badge/license-MIT-green)](#licensing)
68

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*:
810

9-
```
11+
```python
1012
import cv2
1113
print(cv2.cuda.getCudaEnabledDeviceCount())
1214
```
1315

14-
### Installation and Usage
16+
See the [project homepage](https://breakthrough.github.io/opencv-python-cuda/) for more documentation.
1517

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
2019

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
2324

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
2526

26-
**Q: How do I install `opencv-python-cuda`?**
27+
The wheels are too large for PyPI, so they are served from a package index hosted alongside this documentation. Install by name with `pip`:
2728

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`.
29+
```
30+
pip install opencv-python-cuda --extra-index-url https://breakthrough.github.io/opencv-python-cuda/packages/
31+
```
2932

30-
**Q: Can you upload `opencv-python-cuda` to PyPI?**
33+
or with `uv`:
3134

32-
A: No, the package is far too large and exceeds [project size limits](https://docs.pypi.org/project-management/storage-limits/).
35+
```
36+
uv pip install opencv-python-cuda --extra-index-url https://breakthrough.github.io/opencv-python-cuda/packages/
37+
```
3338

34-
**Q: What do the wheels include?**
39+
This installs the newest release, which is **OpenCV 5**. OpenCV 5 has breaking API changes (see the [upstream change logs](https://github.com/opencv/opencv/wiki/OpenCV-Change-Logs)). To stay on OpenCV 4.x, ask for a version below 5:
3540

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+
```
42+
pip install "opencv-python-cuda<5" --extra-index-url https://breakthrough.github.io/opencv-python-cuda/packages/
43+
```
3744

38-
**Q: Why are non-free algorithms excluded?**
45+
The wheel itself downloads from the [Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases) and its SHA-256 hash is verified during installation. `numpy` and other dependencies still come from PyPI. Then import the `cv2` package as usual.
46+
47+
### Manual installation
48+
49+
1. Download the latest `opencv_python_cuda-*-win_amd64.whl` from the [Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases).
50+
2. Install it with `pip` (or another package manager like `uv`):
51+
52+
```
53+
pip install opencv_python_cuda-<version>-win_amd64.whl
54+
```
55+
56+
> [!NOTE]
57+
> 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`.
58+
59+
## What's included
3960

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
61+
- All OpenCV modules that can be built with CUDA support
62+
- Hardware-accelerated video decoding and encoding via NVDEC/NVENC (`cv2.cudacodec`)
63+
- FFmpeg for video I/O
64+
- All required CUDA runtime libraries, bundled in the wheel
4165

42-
### Licensing
66+
Non-free algorithms (e.g. SURF) are excluded - see the FAQ below.
4367

44-
Opencv-python-cuda package (scripts in this repository) is available under MIT license.
68+
## Documentation
69+
70+
- [Project homepage](https://breakthrough.github.io/opencv-python-cuda/) - downloads and overview
71+
- [CUDA Compatibility Reference](https://breakthrough.github.io/opencv-python-cuda/cuda-compatibility.html) - GPU architectures, compute capabilities, and CUDA toolkit support
72+
- [Workflow Guide](https://breakthrough.github.io/opencv-python-cuda/workflow.html) - repository setup, triggering builds, and wheel size strategy
73+
74+
## Frequently Asked Questions
75+
76+
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).
77+
78+
**Q: Which OpenCV versions are available?**
79+
80+
A: Two release lines are maintained: OpenCV 5.x, built from the `5.x-cuda` branch (the default), and OpenCV 4.x, built from the `4.x-cuda` branch. Both are published to the same package index; use a version specifier such as `"opencv-python-cuda<5"` to select 4.x.
81+
82+
**Q: Why can't I `pip install opencv-python-cuda` from PyPI?**
83+
84+
A: The package is far too large for PyPI and exceeds its [project size limits](https://docs.pypi.org/project-management/storage-limits/). Instead, a [PEP 503](https://peps.python.org/pep-0503/) package index is published at `https://breakthrough.github.io/opencv-python-cuda/packages/`, which points at the wheels on the [Releases page](https://github.com/Breakthrough/opencv-python-cuda/releases). Pass it with `--extra-index-url` as shown in [Installation](#installation), or download the wheel manually.
85+
86+
**Q: Is `--extra-index-url` safe to use?**
87+
88+
A: With `--extra-index-url`, `pip` also consults PyPI for the same package name and picks whichever index offers the highest version. `opencv-python-cuda` is not published on PyPI, so this is a theoretical concern only, but if you want to rule it out entirely, download the wheel from the Releases page and install it by file path instead.
89+
90+
**Q: Why does `import cv2` fail with "DLL load failed"?**
91+
92+
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.
93+
94+
**Q: Why are non-free algorithms excluded?**
4595

46-
OpenCV itself is available under [Apache 2](https://github.com/opencv/opencv/blob/master/LICENSE) license.
96+
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.
4797

48-
Third party package licenses are at [LICENSE-3RD-PARTY.txt](https://github.com/opencv/opencv-python/blob/master/LICENSE-3RD-PARTY.txt).
98+
## Licensing
4999

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).
100+
The opencv-python-cuda package (i.e. the scripts in this repository) is available under the MIT license.
51101

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).
102+
- OpenCV itself is available under the [Apache 2](https://github.com/opencv/opencv/blob/master/LICENSE) license.
103+
- 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&reg; CUDA&trade; SDK under the [NVIDIA Software License Agreement (EULA)](https://docs.nvidia.com/cuda/eula/index.html).
104+
- 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).
53105

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).
106+
By downloading and using the software, you agree to fully comply with the terms and conditions of the CUDA EULA.

‎docs/cuda-compatibility.html‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@
55
<meta name="viewport" content="width=device-width, initial-scale=1.0">
66
<title>CUDA Compatibility Reference | opencv-python-cuda</title>
77
<link rel="stylesheet" href="style.css">
8-
<link rel="preconnect" href="https://fonts.googleapis.com">
9-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10-
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@300;400;500;700&display=swap" rel="stylesheet">
118
</head>
129
<body>
1310
<header>

0 commit comments

Comments
 (0)