Registry / ai-ml / albumentations

albumentations

library2.0.8pypypi✓ verified 22d ago

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.

ai-ml

pip install albumentations

package ↗homepage ↗

INSTALL

IMPORT

SIG · ALBUMENTATIONS

albumentations

ai-mlpythonv2.0.8

Install

12.8s avg

Import

2216ms

Disk

410MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 12.8s · import 2.216s · 407MB

410MB installed

● package 410MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Compose

✓ from albumentations import Compose

✓ import albumentations as A

This is the most common and recommended alias.

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

Debug

Known issues

breakingThe 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.

affects: >=2.0.0

gotchaReproducibility 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.

affects: All versions

gotchaAll 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.

affects: All versions

gotchaWhen 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.

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'albumentations'

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

fix

Install the library using pip: `pip install albumentations`.

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

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

fix

Import the module correctly: `from albumentations import augmentations`.

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

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

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

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/.

ValueError: Invalid interpolation method 'random'

An invalid interpolation method is specified in a transformation.

fix

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

Upgrade

Version history

2.0.8latest on PyPI · released May 27, 2025

Audit

Dependencies

opencv-pythonrequiredCore image processing functionalities are built on OpenCV for performance.

numpyrequiredFundamental library for numerical operations and array handling.

Agent activity

94 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/albumentations/ ↗

homepagehttps://albumentations.ai ↗