Albumentations (Legacy - MIT Licensed)

Warnings

• breaking The original MIT-licensed Albumentations library (this package) is no longer actively maintained. The last update was in June 2025, and no further bug fixes, features, or compatibility updates will be provided. This means it may eventually break with newer Python, PyTorch, or TensorFlow versions.
  Fix: Users requiring active development and support should migrate to `AlbumentationsX`. Uninstall `albumentations` and install `albumentationsx` (`pip uninstall albumentations; pip install albumentationsx`). Be aware that `AlbumentationsX` operates under a dual AGPL-3.0 / Commercial license, which may require open-sourcing your project or purchasing a commercial license.
• gotcha Reproducibility of augmentation sequences requires explicitly setting the `seed` parameter in `A.Compose`. Global seeds (`numpy.random.seed()`, `random.seed()`) do not affect Albumentations' internal random state. Additionally, using the same seed with different `num_workers` settings in a PyTorch `DataLoader` will produce different augmentation sequences.
  Fix: Pass a `seed` argument to `A.Compose(..., seed=your_seed)` for reproducible pipelines. If using PyTorch `DataLoader`, understand that `num_workers` can influence augmentation sequences even with a fixed seed.
• gotcha All inputs to Albumentations transforms (images, masks, bounding boxes, keypoints) must be NumPy arrays. Passing Python lists directly is not supported and will result in errors.
  Fix: Ensure all inputs are converted to `numpy.ndarray` before passing them to any Albumentations transform or pipeline.
• gotcha When loading images using OpenCV (`cv2.imread`), they are typically loaded in BGR color space. Albumentations primarily expects images in RGB format. Passing BGR images directly to RGB-sensitive transforms will produce incorrect colors.
  Fix: Explicitly convert BGR images to RGB using `cv2.cvtColor(image, cv2.COLOR_BGR2RGB)` after loading with OpenCV and before passing them to Albumentations.
• gotcha Individual transforms in Albumentations typically require grayscale images to have an explicit channel dimension (e.g., shape `(H, W, 1)` instead of `(H, W)`). While `A.Compose` often provides convenience by handling both formats, it's best practice to ensure the channel dimension is present, especially when applying transforms directly.
  Fix: For grayscale images, ensure they have a channel dimension. If your image is `(H, W)`, use `np.expand_dims(image, axis=-1)` to convert it to `(H, W, 1)`.

Install

• pip install albumentations Install latest stable version

Imports

• Compose

  from albumentations import Compose

• A

  import albumentations as A

  This is the most common and recommended alias.

Quickstart

This quickstart demonstrates how to define a simple augmentation pipeline using `A.Compose` and apply it to an image. It includes common transforms like random cropping, horizontal flipping, and normalization. Ensure `opencv-python` and `numpy` are installed for this example to run.

import albumentations as A
import cv2
import numpy as np

# Create a dummy image (256x256, 3 channels, uint8)
image = np.random.randint(0, 256, (256, 256, 3), dtype=np.uint8)

# Define an augmentation pipeline
transform = A.Compose([
    A.RandomCrop(width=128, height=128, p=1.0),
    A.HorizontalFlip(p=0.5),
    A.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
])

# Apply the transform
transformed_data = transform(image=image)
transformed_image = transformed_data["image"]

print(f"Original image shape: {image.shape}")
print(f"Transformed image shape: {transformed_image.shape}")
print(f"Transformed image dtype: {transformed_image.dtype}")