Installation

On this page

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

Installation Methods

AlbumentationsX offers a commercial license for proprietary applications and services, with agreed coverage for your team and products. It is also available at no charge under AGPL-3.0-only, subject to its terms. Explore commercial licensing or email [email protected]. You can also compare the license options, including the legacy package's MIT license.

Basic Installation

Install the PyTorch build for your platform first. Importing albumentations requires PyTorch even if your pipeline uses only NumPy or trains with TensorFlow/Keras or JAX. The package leaves the CPU, CUDA, or MPS build choice to your application.

Then choose one OpenCV variant. OpenCV is required at runtime, but installed only when you select an extra or install it separately. The current extras require OpenCV 5.x.

For GUI support (desktop environments, visualization):

python -m pip install -U "albumentationsx[gui]"

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

python -m pip install -U "albumentationsx[headless]"

For OpenCV contrib modules:

python -m pip install -U "albumentationsx[contrib]"

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

python -m pip install "opencv-python>=5.0.0.93"
python -m 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)

After installing PyTorch and an OpenCV variant:

python -m 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.

Optional Triton acceleration on CUDA

Triton is optional. On Linux with an NVIDIA GPU of compute capability 8.0 or newer, InputNormalizer can use Triton for supported FP16 and BF16 outputs. Without Triton, it uses PyTorch.

Your CUDA PyTorch environment may already include Triton. Check in the same environment where you run training.

python -c "import triton; print(triton.__version__)"

To enable the fused path if Triton is missing, install a version compatible with your PyTorch build. See the Triton installation instructions and the supported normalization modes and dtypes.

Understanding OpenCV Dependencies

Albumentations relies heavily on OpenCV for image processing operations.

Choose one OpenCV distribution

The OpenCV packages share the cv2 namespace. Install one distribution in an environment; combining gui, headless, and contrib variants can create conflicts. Albumentations does not inspect or remove variants you installed separately.

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

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

  • Use contrib modules on servers without GUI dependencies

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

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.

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: Compare commercial coverage with AGPL and find answers about internal training, model outputs, and customer deliveries.