🧩 OpenCV dependency handling (important change)

What was happening before

For a long time, Albumentations tried to be “smart” about OpenCV:

• If an OpenCV package (opencv-python, opencv-contrib-python, etc.) was already installed, it attempted to reuse it
• If no OpenCV was detected, it automatically pulled in opencv-python-headless

The intention was convenience — to make things “just work”.

In practice, however, this approach caused persistent problems.

A very common failure mode was:

• A user already had opencv-python installed
• Installing Albumentations also installed opencv-python-headless
• Both packages provide cv2
• At runtime, the import order became undefined
• GUI features such as cv2.imshow() stopped working

This led to broken environments and a steady stream of frustrated reports (see #124).

---

Why this could not be fixed reliably

This turned out to be not a simple bug, but a fundamental limitation of Python packaging.

Dependency logic in setup.py / pyproject.toml is evaluated when wheels are built, not when users install them. Builds happen in isolated environments (PEP 517), which means:

• The user’s existing environment is not visible
• Importing cv2 during build does not reflect what the user actually has installed
• Conditional logic like “only install headless if OpenCV is missing” cannot work correctly

After many attempts over the years, it became clear that this problem cannot be solved robustly with heuristics.

---

What changed

Starting with AlbumentationsX 2.0.14, OpenCV is now a purely optional dependency.

AlbumentationsX now:

• Does not install OpenCV implicitly
• Does not try to guess which OpenCV variant you want
• Will never install conflicting OpenCV packages

This makes installs predictable and environments stable.

---

How to install now

You explicitly choose the OpenCV variant that matches your setup:

• GUI support:

  pip install albumentationsx[gui]
  

• Headless / server environments:

  pip install albumentationsx[headless]
  

• Contrib modules:

  pip install albumentationsx[contrib]
  

• Manual control:

  pip install opencv-python
  pip install albumentationsx
  

No hidden installs, no surprises.

---

Why this is better

This change removes an entire class of long-standing issues by making dependency choice explicit.

It trades a bit of automation for:

• Stable environments
• Clear behavior
• No silent breakage
• Fewer “why did this suddenly stop working?” moments

In short: less magic, more reliability.

---

💬 Feedback, support, and next steps

Issues & feature requests

If you run into issues, have questions, or want to suggest improvements — please open an issue on GitHub:

👉 https://github.com/albumentations-team/AlbumentationsX/issues

Clear reports and real-world feedback genuinely help improve the project.

---

📄 Licensing (important)

AlbumentationsX uses a dual-license model:

• AGPL — for open-source projects and research
• Commercial license required — for proprietary or closed-source commercial use

If AlbumentationsX is part of a commercial product, please make sure you have an appropriate commercial license.

---

❤️ Supporting the project

If you’re an individual developer or researcher and AlbumentationsX has been useful to you, thank you — that truly means a lot.

If you’d like to support the work:

• GitHub Sponsors is a simple option
• Even a small, monthly “coffee-sized” contribution helps keep maintenance sustainable

It’s a quiet way to say thanks and support long-term development.

👉 https://github.com/sponsors/albumentations-team