Installation

Albumentations requires Python 3.10 or higher. We recommend using the latest stable Python version.

Installation Methods

Albumentations offers:

• ⚡ Improved performance and bug fixes
• 🔧 Active maintenance and new features
• 📊 Better support for production environments

Albumentations is dual-licensed (AGPL/Commercial). For more information about licensing, see our License Guide.

Basic Installation

Important: Starting with Albumentations 2.0.14, OpenCV is not installed automatically. You need to explicitly choose your OpenCV variant:

For GUI support (desktop environments, visualization):

pip install -U albumentationsx[gui]

For headless environments (servers, Docker, CI/CD):

pip install -U albumentationsx[headless]

For OpenCV contrib modules:

pip install -U albumentationsx[contrib]

Manual OpenCV installation (if you already have OpenCV or want full control):

pip install opencv-python  # or opencv-python-headless, opencv-contrib-python, etc.
pip install -U albumentationsx

Here's a basic example:

import albumentations as A

transform = A.Compose([
    A.RandomCrop(width=256, height=256),
    A.HorizontalFlip(p=0.5),
    A.RandomBrightnessContrast(p=0.2),
])

From GitHub (Latest Development Version)

For Albumentations:

pip install -U git+https://github.com/albumentations-team/AlbumentationsX

Note: Installing from the main branch might give you newer features but could potentially be less stable than official releases.

Understanding OpenCV Dependencies

Albumentations relies heavily on OpenCV for image processing operations.

Why OpenCV is now optional (Albumentations 2.0.14+)

Previously, Albumentations tried to automatically manage OpenCV installation, which caused persistent issues:

• Conflicting OpenCV packages (opencv-python and opencv-python-headless) could be installed simultaneously
• GUI features like cv2.imshow() would break unexpectedly
• Import order became unpredictable

The root cause: Python's build system evaluates dependencies in isolated environments, making it impossible to reliably detect what's already installed in your environment.

The new approach

Starting with version 2.0.14, Albumentations:

• ✅ Does not install OpenCV automatically
• ✅ Does not try to guess which variant you need
• ✅ Will never install conflicting OpenCV packages
• ✅ Gives you explicit control over your environment

Choosing the right OpenCV variant

albumentationsx[gui] - Installs opencv-python:

• Use for desktop applications
• Includes GUI support (cv2.imshow(), cv2.waitKey(), etc.)
• Larger installation size

albumentationsx[headless] - Installs opencv-python-headless:

• Use for servers, Docker containers, CI/CD pipelines
• No GUI dependencies
• Smaller installation size

albumentationsx[contrib] - Installs opencv-contrib-python:

• Includes additional OpenCV modules
• Use when you need extended functionality

Manual installation - Install OpenCV separately:

• Maximum control over the exact version and variant
• Useful if you have custom OpenCV builds
• Install your preferred OpenCV package first, then Albumentations

Why this is better

This change trades a bit of automation for:

• 🔒 Stable, predictable environments
• 🎯 Clear, explicit behavior
• 🚫 No silent breakage or conflicts
• 💡 Fewer "why did this suddenly stop working?" moments

Less magic, more reliability.

Verify Installation

After installation, you can verify it by running:

python -c "import albumentations as A; print(A.__version__)"

This should print the installed version number.

Telemetry in Albumentations

Albumentations includes anonymous usage telemetry to help improve the library. This can be disabled by:

Setting an environment variable:

export ALBUMENTATIONS_NO_TELEMETRY=1

Or per-pipeline:

transform = A.Compose([...], telemetry=False)

Learn more in our License Guide.

Where to Go Next?

Now that you have Albumentations installed, here are some logical next steps:

• Understand Core Concepts: Learn about transforms, pipelines, targets, and probabilities - the fundamental building blocks of Albumentations.
• See Basic Usage Examples: Explore how to apply augmentations for common computer vision tasks.
• Explore Transforms: Visually experiment with different augmentations and their parameters.
• License Guide: If using Albumentations, understand the dual licensing model.