AlbumentationsX vs Legacy Albumentations

On this page

Choose AlbumentationsX for a pipeline that needs ongoing library development, FP16 images or volumes, CPU torch.Tensor input, oriented bounding boxes, linked per-object annotations, or more extensive 3D augmentation. It keeps the familiar Compose workflow and import albumentations as A.

The legacy albumentations package remains available under MIT. Its repository is archived, and its last release is 2.0.8. Keeping that version can make sense when reproducing an existing experiment or maintaining an environment whose dependencies must stay fixed.

This page compares AlbumentationsX 2.6.0 with legacy Albumentations 2.0.8, verified on November 7, 2026. The latest main source was also checked at fbba9b7. Post-release changes are identified below. The migration steps cover installation and the behavior to check before switching.

What changes when you switch

Both libraries already synchronize images with built-in annotation targets, support custom transforms, and provide ReplayCompose and pipeline serialization. Those are shared capabilities. The differences below are reasons to evaluate AX for an existing workload.

Your requirementLegacy Albumentations 2.0.8AlbumentationsX 2.6.0
Receive upstream fixes and new featuresArchived repository; last release May 2025Maintained release line
Augment data already stored as PyTorch tensorsNumPy pipeline input; conversion to Tensor follows augmentationCPU Tensor input and output; NumPy and Tensor can be mixed across targets
Keep floating images and volumes in half precisionDocumented uint8/float32 image path; no FP16 pipeline contractNumPy and CPU Tensor FP16, including collections and reference/donor inputs
Mix collated training examples or normalize on the model deviceNo albumentations.batch modulesample_mixup, apply_mixup, and InputNormalizer outside Compose
Select video frames together with their annotationsShared spatial augmentation across framesAdds UniformTemporalSubsample and explicit frame_binding
Keep one object's mask, box, and pose together when filteringSeparate target arraysinstance_binding removes the bound annotations together
Train with oriented bounding boxes (OBB)Axis-aligned boxesbbox_type="obb" with validation of the transforms in the pipeline
Preserve left/right annotation semantics after a reflectionApplication code handles semantic label changesConfigured mappings for keypoint labels and semantic-mask class IDs
Apply geometry in three dimensions3D crops, padding, dropout, and cubic symmetryAdds affine transforms, resizing, elastic deformation, and more discrete 3D operations
Inspect intermediate results and sampled choicesReplay and applied-parameter loggingAdds execution traces, optional snapshots and timings, and applied-configuration reconstruction
Choose license termsMITCommercial license with agreed coverage, or AGPL-3.0-only at no charge under its terms

A commercial agreement can cover proprietary integration and customer delivery for the teams and products you name. Request a quote or email [email protected]. Compare both options in the license guide. The AGPL permits commercial use subject to its terms; migration itself does not create a payment requirement. The 2.6.0 licensing notice records the license for the version compared here.

Pass CPU tensors directly into Compose

If your decoder or dataset already returns a CPU torch.Tensor, pass it directly to Compose. Image tensors use channel-first layout. A Tensor input returns as a Tensor, so the pipeline does not need a terminal conversion transform.

NumPy and Tensor containers are independent for each target. This example crops and flips a Tensor image with a NumPy segmentation mask. Each result keeps its input container, and the mask follows the image geometry.

import albumentations as A
import numpy as np
import torch

image = torch.arange(72, dtype=torch.uint8).reshape(3, 4, 6)
mask = np.zeros((4, 6), dtype=np.uint8)
mask[1:3, 1:3] = 1

transform = A.Compose(
    [A.CenterCrop(height=2, width=4), A.HorizontalFlip(p=1.0)],
    seed=137,
)

result = transform(image=image, mask=mask)

assert isinstance(result["image"], torch.Tensor)
assert result["image"].shape == (3, 2, 4)
assert isinstance(result["mask"], np.ndarray)
torch.testing.assert_close(result["image"], image[:, 1:3, 1:5].flip(-1))
np.testing.assert_array_equal(result["mask"], mask[1:3, 1:5][:, ::-1])

Accepted Tensor shapes and dtypes

N is the number of images, masks, or annotation rows; C is channels; D, H, and W are depth, height, and width.

TargetTensor shape accepted by ComposeTensor dtypes
image(C, H, W) or grayscale (H, W)uint8, float16, float32
images(N, C, H, W)uint8, float16, float32
volume(C, D, H, W)uint8, float16, float32
volumes(N, C, D, H, W)uint8, float16, float32
mask(C, H, W) or (H, W)uint8, int16, float16, float32
masks(N, C, H, W) or (N, H, W)uint8, int16, float16, float32
mask3d(C, D, H, W) or (D, H, W)uint8, int16, float16, float32
masks3d(N, C, D, H, W) or (N, D, H, W)uint8, int16, float16, float32
bboxes, keypoints(N, K), where K follows the configured coordinate formatfloat32

For video passed as images, N is the frame count. The Tensor layout is (T, C, H, W); ordinary DataLoader collation adds a batch axis to produce (B, T, C, H, W).

Inputs must be plain CPU torch.Tensor values with torch.strided layout and requires_grad=False. CUDA and MPS tensors, Tensor subclasses, and unlisted dtypes are outside this input contract. Image values use uint8 in [0, 255] or float16/float32 in [0, 1]. Image normalization is an explicit transform in the policy.

When an input omits a supported channel axis, Compose restores that shape if the output still has one channel. NumPy inputs keep their channel-last convention, including (D, H, W) or (D, H, W, C) for a volume.

How Tensor support affects your pipeline

  • Remove terminal converters for Tensor input. ToTensorV2 and ToTensor3D accept NumPy input only. If any supplied target is a Tensor, either converter anywhere in the selectable pipeline causes an error, even if its probability is zero.
  • CPU augmentation works with GPU training. Run augmentation in your dataset or DataLoader, then transfer the resulting batch to the model's device.
  • Execution depends on each applied transform. Tensor-aware handlers run directly. Other transforms convert the Tensor targets they use to NumPy and restore them afterward. This fallback occurs per transform; adjacent transforms can each perform a conversion. A skipped transform performs none.

The NumPy and Tensor input guide for 2.6.0 covers additional targets, annotation processing, and conversion behavior.

Keep floating images and volumes in FP16

AX 2.6.0 accepts NumPy float16 and eager CPU torch.float16 for images, volumes, their collections, supported masks, and reference/donor data. Dtype-preserving transforms retain FP16. This halves the stored bytes per value relative to float32; wider temporary arithmetic means peak memory and runtime still need measurement on your policy.

import albumentations as A
import numpy as np
import torch

image = np.linspace(0, 1, 4 * 6 * 3, dtype=np.float16).reshape(4, 6, 3)
transform = A.Compose([A.HorizontalFlip(p=1.0), A.ToFloat()], seed=137)
array_result = transform(image=image)["image"]
tensor_image = torch.from_numpy(image).permute(2, 0, 1)
tensor_result = transform(image=tensor_image)["image"]

assert array_result.dtype == np.float16
assert tensor_result.dtype == torch.float16
np.testing.assert_array_equal(array_result, image[:, ::-1])
torch.testing.assert_close(tensor_result, tensor_image.flip(-1))

Normalize returns FP16 for FP16 input, including per-image modes. ToFloat preserves FP16 input and converts uint8 to float32; FromFloat produces uint8. ToTensorV2 and ToTensor3D preserve FP16 when converting NumPy targets. Bboxes, keypoints, and geometry keep their existing precision contracts. Keep categorical mask IDs in an integer dtype when exact IDs matter.

FP16 input does not enable CUDA/MPS execution or autograd in Compose. For a collated batch on the model device, use the separate batch API below. The target guide covers dtype and layout choices.

Mix and normalize collated batches

The albumentations.batch module runs after collation. sample_mixup creates a reusable plan of donor indices and weights; apply_mixup applies that plan to images or volumes and floating targets that can validly be interpolated. InputNormalizer scales, normalizes, and casts channel-first image or volume batches, with FP32 arithmetic and FP32, FP16, or BF16 output.

These operations run outside autograd and return inputs for the model's trainable step. They use the batch device, independently of the CPU-only Compose boundary. See Batch Augmentations for a complete example and target constraints.

Select video frames with their annotations

UniformTemporalSubsample(num_frames=...) selects evenly spaced frames, repeating frames when the requested clip is longer than the input. frame_binding=["images", "masks"] keeps one semantic mask attached to each selected frame; frame_binding=["images", "frame_annotations"] supports per-frame annotation dictionaries. This adds temporal selection to the shared spatial augmentation already available in legacy. See Video Augmentation.

Keep object annotations and labels consistent

Filter all annotations belonging to one object together

An instance-segmentation sample can contain one box and mask per object. A crop may remove a box while leaving the corresponding mask entry in a separately managed array. Pose data adds another set of rows that must stay attached to the same object.

With instance_binding, each object is supplied as a dictionary in instances. Configure the fields that belong together, such as instance_binding=["masks", "bboxes"]. If bbox filtering removes an object, its bound fields are removed too. When a mask and bbox are bound, an empty transformed mask also removes the object. This relationship is maintained through crops and mixing operations such as Mosaic and CopyAndPaste.

Use this for per-object masks, boxes, and pose groups. A single semantic-segmentation mask containing class IDs uses the ordinary mask target. The instance segmentation guide gives the input structure and filtering rules.

Describe rotated objects with oriented bounding boxes

For aerial objects, text regions, or other objects whose orientation matters, set bbox_type="obb" in BboxParams. The box representation includes an angle. Compose checks geometric transforms when the pipeline is constructed and rejects operations without OBB support.

Support is specific to the transform. The oriented bounding boxes guide lists coordinate formats and shows a complete pipeline.

Remap left/right labels after a reflection

A geometric flip moves pixels and coordinates. It also changes the meaning of a label such as left_eye or a semantic-mask class representing the left side of an organ. Configure that relationship with KeypointParams.label_mapping or semantic_mask_label_mappings.

Mappings run when the relevant orientation-changing event occurs. The library needs an explicit mapping; it cannot infer the meaning of class IDs or label names. For paired 2D landmarks, remapping can reorder complete keypoint records to preserve the landmark index convention. Three-dimensional keypoint remapping changes label values while retaining transformed row order.

For the mapping fields and examples, see the 2.6.0 KeypointParams reference in source and Compose semantic-mask options.

Build policies that operate in three dimensions

AX expands the geometry you can apply to a volume and its annotations:

What you want to simulate or changeAX transforms
Rotation, scaling, and translation in 3DAffine3D
Resampling depth, height, and widthResize3D
Smooth nonrigid volume deformationElasticTransform3D, added in 2.4.4
Reflections, right-angle rotations, or shuffled volume blocksFlip3D, RandomRotate90_3D, GridShuffle3D
Lower acquisition resolution along selected axesAnisotropy3D

Check each transform's target support when combining a volume, mask3d, and xyz keypoints. For example, acquisition degradation with Anisotropy3D changes the volume while leaving annotations unchanged. Physical spacing, orientation, and imaging affines remain your data layer's responsibility; array augmentation does not update that metadata.

See volumetric augmentation for layouts and example policies.

Inspect a sample at each step

When an augmented sample looks wrong, AX can show the decisions and intermediate data that produced it. run_with_trace records applied and skipped steps. TraceOptions can request snapshots of selected targets and per-transform timings; tracing is off by default.

Three tools answer different debugging questions:

Your questionAPI to use
Which step changed this sample?run_with_trace, optionally with TraceOptions(snapshot_targets=("image", "bboxes"))
Which constructor choices were realized?save_applied_params=True and Compose.from_applied_transforms(...)
How do I repeat the sampled crop coordinates, dropout mask, and other runtime parameters?ReplayCompose

Legacy already has ReplayCompose. AX's applied-configuration reconstruction is an additional inspection tool: it makes a runnable policy from realized constructor settings, but those settings alone do not preserve every random array or sampled coordinate. Use Replay and Applied-Parameter Debugging to choose the appropriate mechanism.

Recent additions for imaging workloads

These examples highlight additions and extensions available in 2.6.0. Each transform's Explore page describes its parameters and supported targets.

WorkloadCapability
MRI acquisition artifactsBiasField, GhostingArtifact, GibbsRinging, and MotionArtifact add intensity inhomogeneity and k-space artifact policies.
MRI spikes and magnitude noiseKSpaceSpikeNoise adds Fourier-domain spikes to images or volumes; introduced in 2.4.4. RicianNoise provides magnitude-MRI noise simulation.
Appearance variation through random filteringStochasticConvolution applies randomly perturbed convolution kernels; introduced in 2.4.4.
Uneven lighting with several illuminated regionsIllumination supports multiple Gaussian spots in 2.4.4.
Histology with a known stain basisHEStain extends custom stain-matrix support to complete (3, 3) bases.
Detection with constrained crops or pasted objectsBBoxSubsetSafeRandomCrop, LetterBox, and CopyAndPaste

Performance

If augmentation cannot prepare the next batch in time, the GPU waits. For training workloads, measure the complete DataLoader pipeline with your worker count, batch size, image sizes, and transform sequence. A faster individual transform helps only to the extent that it reduces the bottleneck in that pipeline.

The RGB benchmark includes DataLoader pipelines and individual-transform measurements. The multichannel and video results cover other input shapes. Read the package versions, hardware, execution route, and methodology alongside each result.

To measure the benefit of migrating from legacy, run both pinned versions on equivalent inputs and policies in separate environments. The published RGB benchmark does not establish a legacy-to-AX speedup unless both versions appear in the same measured workload. Tensor input support also does not guarantee a faster policy: the applied transforms may use NumPy fallback.

Migrate an existing pipeline

Install the runtime and package

Use a separate environment for AX while keeping the legacy environment available for comparison. Both distributions install the albumentations Python namespace; do not install them together.

First install the PyTorch build appropriate for your operating system and CPU, CUDA, or MPS setup using the PyTorch installation selector. AX requires PyTorch at import time even when you pass NumPy arrays or train with TensorFlow, Keras, or JAX. The package does not install or select a PyTorch build for you.

Then install AX with an OpenCV variant. For a server or container without GUI support, this command installs the version reviewed on this page:

python -m pip install "albumentationsx[headless]==2.6.0"

Choose gui, contrib, or contrib-headless instead when those OpenCV capabilities are needed. If you already manage OpenCV separately, install albumentationsx==2.6.0 without an OpenCV extra.

The Python import stays the same:

import albumentations as A

assert A.__version__ == "2.6.0"

Check the policy on representative samples

  1. Start with your existing augmentation policy. Check constructor parameters and warnings against the selected AX release. Coordinate processors use coord_format, and range arguments use current names such as Rotate.angle_range and Blur.blur_range. ChannelDropout uses channels_to_drop and dropout_ratio instead of channel_drop_range; for one dropped RGB channel, set dropout_ratio=1 / 3. Keeping the import name does not guarantee identical behavior across versions.
  2. Check the data boundary. Compare output shapes, dtypes, value ranges, bbox formats, keypoint labels, and any filtered objects. For Tensor input, use the shapes above and remove terminal Tensor converters.
  3. Check annotations visually. Include small objects, partly cropped objects, left/right labels, and 3D samples if they occur in your dataset. A matching image shape alone cannot establish annotation correctness.
  4. Add capabilities where your data needs them. Introduce instance binding, semantic remapping, or OBB processing with samples that exercise the corresponding behavior.
  5. Measure the workload you intend to run. Compare loader throughput and training step time with the same inputs and resources. Use a fixed evaluation protocol to assess model quality; the same random seed need not produce identical augmentations across library versions.

Changes already merged after 2.6.0

The checked main revision adds guarantees and fixes beyond the release compared above:

  • Root validation runs before probability and sampling draws, including p=0 and traced calls; rejected root inputs do not advance the configured stream.
  • Geometry fixes cover OBB refitting under unequal resize scales, perspective and remap geometry, and annotation mapping when replaying resize operations on a different frame size.
  • ReplayCompose records ordered and repeated visits through SomeOf and RandomOrder. Older records remain readable, but cannot recover visit information they never saved.

Use the development revision for those changes, or wait for a release that contains it. See the validation, geometry, and determinism contracts for the current behavior.

Versioned sources