Albumentations (Legacy - MIT Licensed)

2.0.8 verified Thu Apr 09 auth: no python abandoned

Albumentations is a Python library for image augmentation, widely adopted in deep learning and computer vision tasks for its speed, flexibility, and extensive collection of transformations. It offers a unified API to work with various data types including images, masks, bounding boxes, and keypoints. **However, the original MIT-licensed Albumentations project is no longer actively maintained. The last update was in June 2025, and no further bug fixes, features, or compatibility updates will be provided.** For active development and support, users are directed to its successor, AlbumentationsX, which maintains the same API but operates under a dual AGPL-3.0 / Commercial license. The current version of this legacy library is 2.0.8.

pip install albumentations

Common errors

error ModuleNotFoundError: No module named 'albumentations' ↓

cause The 'albumentations' library is not installed in the current Python environment.

fix

Install the library using pip: pip install albumentations.

error ImportError: cannot import name 'augmentations' from 'albumentations' ↓

cause The 'augmentations' module is not directly importable from 'albumentations'.

fix

Import the module correctly: from albumentations import augmentations.

error AttributeError: module 'albumentations' has no attribute 'Compose' ↓

cause The 'Compose' class is not found in the 'albumentations' module, possibly due to an outdated version.

fix

Ensure you have the latest version installed: pip install --upgrade albumentations.

error TypeError: __init__() got an unexpected keyword argument 'p' ↓

cause An incorrect argument is passed to an augmentation function, likely due to API changes.

fix

Refer to the latest documentation for correct usage: https://albumentations.ai/docs/.

error ValueError: Invalid interpolation method 'random' ↓

cause An invalid interpolation method is specified in a transformation.

fix

Use a valid interpolation method such as 'nearest' or 'bilinear'.

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)`.

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}")