Skip to content

Make OpenCV an optional dependency to support contrib variants #2139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 11 commits into
base: develop
Choose a base branch
from
Draft

Make OpenCV an optional dependency to support contrib variants #2139

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9518918
Initial plan
Copilot Feb 6, 2026
45c9402
Make OpenCV an optional dependency with multiple variants
Copilot Feb 6, 2026
4d9133b
Add changelog entry for OpenCV optional dependency change
Copilot Feb 6, 2026
b4b3422
Wrap all cv2 imports with try/except and add ensure_cv2_installed() c…
Copilot Feb 6, 2026
b7aba15
Fix cv2 constant usage at module level and update CI workflows
Copilot Feb 6, 2026
63524a5
Merge branch 'develop' into copilot/fix-opencv-dependency-issue
Borda Feb 12, 2026
a59d3c2
Update README.md
Borda Feb 12, 2026
e04444b
Update docs/index.md
Borda Feb 12, 2026
fa05b19
Update README.md
Borda Feb 12, 2026
f88b612
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Feb 12, 2026
2b67b3d
Address PR review feedback: complete installation docs and clarify ru…
Copilot Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,19 @@
Pip install the supervision package in a
[**Python>=3.9**](https://www.python.org/) environment.

```bash
pip install supervision[headless]
```

Supervision requires OpenCV. We don't enforce a specific version to avoid conflicts with other packages. Choose the OpenCV variant that best fits your needs:

- `supervision[headless]` - Install with `opencv-python-headless` (recommended for servers)
- `supervision[desktop]` - Install with `opencv-python` (includes GUI support)
- `supervision[desktop-contrib]` - Install with `opencv-contrib-python` (extra modules + GUI)
- `supervision[headless-contrib]` - Install with `opencv-contrib-python-headless` (extra modules, no GUI)

If you have OpenCV already installed, you can install supervision without any extras:

```bash
pip install supervision
```
Expand Down
14 changes: 14 additions & 0 deletions docs/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Changelog

### 0.28.0rc0 <small>Unreleased</small>

!!! breaking "Breaking Change"
**OpenCV is now an optional dependency.** To ensure compatibility with different OpenCV variants (standard, contrib, headless), `opencv-python` has been removed from the core dependencies. Users must now explicitly choose their preferred OpenCV package:

- `pip install supervision[headless]` - Installs `opencv-python-headless` (recommended for servers)
- `pip install supervision[desktop]` - Installs `opencv-python` (includes GUI support)
- `pip install supervision[desktop-contrib]` - Installs `opencv-contrib-python` (extra modules + GUI)
- `pip install supervision[headless-contrib]` - Installs `opencv-contrib-python-headless` (extra modules, no GUI)

If you already have OpenCV installed, you can install supervision without extras: `pip install supervision`

This change resolves conflicts where `opencv-python` would override `opencv-contrib-python`, preventing access to extra modules like CSRT tracker.
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The breaking change notice should clarify the runtime behavior more explicitly. Currently it states "OpenCV is now an optional dependency" which could be interpreted as "supervision works without OpenCV."

Consider rephrasing to be more explicit about the requirement:

"OpenCV is required at runtime but is now an optional install-time dependency. To ensure compatibility with different OpenCV variants (standard, contrib, headless), opencv-python has been removed from the core dependencies. Users must now have OpenCV installed either by:

  • Explicitly choosing an OpenCV extra when installing supervision (recommended)
  • Having a compatible OpenCV package already installed

Without OpenCV installed, import supervision will fail with an ImportError."

This makes it clear that OpenCV is still required to use the library, just not automatically installed.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@Borda Borda Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Copy Markdown
Contributor Author

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in commit 2b67b3d. Clarified that "OpenCV is required at runtime but is now an optional install-time dependency" and added a note explaining that functions will raise ImportError without OpenCV installed. This makes it clear OpenCV is still required to use the library.


### 0.27.0 <small>Nov 16, 2025</small>

- Added [#2008](https://github.com/roboflow/supervision/pull/2008): [`sv.filter_segments_by_distance`](https://supervision.roboflow.com/0.27.0/detection/utils/masks/#supervision.detection.utils.masks.filter_segments_by_distance) to keep the largest connected component and nearby components within an absolute or relative distance threshold. Useful for cleaning segmentation predictions from models such as SAM, SAM2, YOLO segmentation, and RF-DETR segmentation.
Expand Down
39 changes: 35 additions & 4 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,30 @@ You can install `supervision` in a
[![license](https://img.shields.io/pypi/l/supervision)](../LICENSE.md)
[![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)

Supervision requires OpenCV. Choose the variant that best fits your needs:

```bash
# Recommended for servers (no GUI)
pip install supervision[headless]
```

```bash
# For desktop applications (includes GUI support)
pip install supervision[desktop]
```

```bash
# For desktop with extra modules (e.g., CSRT tracker)
pip install supervision[desktop-contrib]
```

```bash
# For servers with extra modules (no GUI)
pip install supervision[headless-contrib]
```

If you already have OpenCV installed:

```bash
pip install supervision
```
Comment on lines +51 to 79
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a warning in the installation documentation that users should only install ONE OpenCV variant at a time. The different opencv-python packages are mutually exclusive and installing multiple extras that include different OpenCV variants will cause conflicts.

For example, add a note like:
"⚠️ Important: Only install one OpenCV variant at a time. The different opencv-python packages (standard, contrib, headless, etc.) are mutually exclusive and cannot coexist in the same environment."

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@Borda Borda Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Copy Markdown
Contributor Author

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in commit 2b67b3d. Added warning in the pip installation section:

⚠️ Important: Only install one OpenCV variant at a time. The different opencv-python packages (standard, contrib, headless, etc.) are mutually exclusive and cannot coexist in the same environment.

Expand All @@ -60,7 +84,13 @@ You can install `supervision` in a
[![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)

```bash
poetry add supervision
# With headless OpenCV (recommended for servers)
poetry add supervision[headless]
```

```bash
# With desktop OpenCV (includes GUI)
poetry add supervision[desktop]
```

=== "uv"
Expand All @@ -71,13 +101,14 @@ You can install `supervision` in a
[![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)

```bash
uv pip install supervision
# With headless OpenCV (recommended for servers)
uv pip install supervision[headless]
```

For uv projects:

```bash
uv add supervision
uv add supervision --extra headless
```
Comment on lines 115 to 145
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The uv installation instructions are incomplete compared to the pip section. The pip section shows all four OpenCV variants with descriptive comments, but the uv section only shows the headless variant. For consistency and to help users make informed choices, add the other variants:

# For desktop applications (includes GUI support)
uv pip install supervision[desktop]
# For desktop with extra modules (e.g., CSRT tracker)
uv pip install supervision[desktop-contrib]
# For servers with extra modules (no GUI)
uv pip install supervision[headless-contrib]

Also add: "If you already have OpenCV installed: uv pip install supervision"

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@Borda Borda Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Copy Markdown
Contributor Author

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in commit 2b67b3d. Added all 4 OpenCV variants to the uv installation section with descriptive comments, plus instructions for when OpenCV is already installed.


=== "rye"
Expand All @@ -88,7 +119,7 @@ You can install `supervision` in a
[![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision)

```bash
rye add supervision
rye add supervision --features headless
```
Comment on lines 154 to 157
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rye installation instructions are incomplete compared to other installation methods. Only the headless variant is shown. For consistency and to help users make informed choices, add examples for the other variants:

# For desktop applications (includes GUI support)
rye add supervision --features desktop
# For desktop with extra modules (e.g., CSRT tracker)
rye add supervision --features desktop-contrib
# For servers with extra modules (no GUI)
rye add supervision --features headless-contrib

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@Borda Borda Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Copy Markdown
Contributor Author

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in commit 2b67b3d. Added all 4 OpenCV variants to the rye installation section with descriptive comments matching the other package managers.


!!! example "conda/mamba install"
Expand Down
13 changes: 12 additions & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,25 @@ dependencies = [
"defusedxml>=0.7.1",
"matplotlib>=3.6",
"numpy>=1.21.2",
"opencv-python>=4.5.5.64",
"pillow>=9.4",
"pyyaml>=5.3",
"requests>=2.26",
"scipy>=1.10",
"tqdm>=4.62.3",
]

optional-dependencies.headless = [
"opencv-python-headless>=4.5.5.64",
]
optional-dependencies.desktop = [
"opencv-python>=4.5.5.64",
]
optional-dependencies.desktop-contrib = [
"opencv-contrib-python>=4.5.5.64",
]
optional-dependencies.headless-contrib = [
"opencv-contrib-python-headless>=4.5.5.64",
]
optional-dependencies.metrics = [
"pandas>=2",
]
Expand Down
Loading