Albumentations

AlbumentationsX vs Legacy Albumentations: Practical Benefits

On this page

AlbumentationsX gives you correct, fast, debuggable augmentation for the workloads where in-house augmentation pipelines normally fail — instance segmentation, pose, rotated detection, multichannel, and video. The API is close to drop-in with torchvision.transforms and other PyTorch-side augmentation libraries, so switching is measured in minutes, not days.

The legacy albumentations package on PyPI is archived. No more security patches, no more bug fixes, no compatibility updates for new Python / NumPy / PyTorch / OpenCV releases. Staying on it means accepting the package frozen as it is, forever.

This page covers what you get technically. For the legal side, see the License Guide.

The Legacy Package Is No Longer Maintained

The legacy albumentations package is not "stable" in the sense that it is maintained and reliable. It is frozen. There is a difference:

  • No security patches. If a CVE is filed against a dependency or a vulnerability is found in the library itself, nobody will fix it in the legacy package.
  • No compatibility updates. When NumPy 2.x extensions, a future PyTorch major version, an OpenCV major version, or Python 3.14+ break something, the legacy package will not be patched.
  • No CVE response process. No SECURITY.md, no disclosure channel, no published SLA for the package or its transitive dependencies.
  • No bug fixes. Known correctness issues in replay, serialization, instance and pose target alignment, and data-loader randomness will remain.
  • No new transforms, no new annotation targets, no performance work.

If your team depends on a frozen, unsupported package, that is a risk your security and compliance review should know about.

Switching takes minutes

The API is close to drop-in with torchvision.transforms and Kornia. If you already have a PyTorch, TensorFlow, or JAX pipeline, the augmentation step swaps in without a framework change, without a CUDA build, without a JIT compile step, and without reformatting your bounding boxes, masks, or keypoints — Pascal VOC, COCO, and YOLO formats are all native.

pip install albumentationsx

import albumentations as A

That is the whole migration surface for most pipelines.

What you write yourself if you don't use Albumentations

On PIL, OpenCV, or raw NumPy, every transform is your code: the geometry, the bounding-box math, the mask math, the keypoint math. Rotated bounding boxes, semantic keypoint label swapping for pose flips, copy-paste with correct mask propagation, mosaic with aligned indices — these are the standard places in-house augmentation stacks have silent bugs.

Then you maintain all of it through NumPy 2.x, future PyTorch major versions, OpenCV major versions, and Python upgrades. Every dependency bump becomes a porting project for code that should not be your team's job to own.

Which Teams Should Care

Workload or teamWhat you can doWhat you give up if you stay on legacy
Teams with compliance or security review requirementsPoint your security review at OIDC trusted publishing, signed releases with SBOMs, a reproducible lockfile, and a documented SECURITY.md.Your security review flags an unsupported, unpatched dependency with no SBOM, no disclosure process, and no upgrade path for the package or its transitive dependencies.
Rotated object detection (OCR, aerial, industrial inspection, document analysis)Train rotated detectors with native oriented-bbox support across pad, crop, mosaic, and the full transform set.You implement and maintain rotated-bbox geometry yourself for every transform you need, or you ship axis-aligned and pretend.
Instance segmentation, pose, and copy-paste pipelinesRun pipelines knowing masks, bounding boxes, and keypoints stay aligned per object across the whole pipeline — including Mosaic and CopyAndPaste.Filtering one target leaves the others stale. Silent supervision drift is the canonical failure mode of in-house instance and pose augmentation.
Pose estimation or facial landmarksFlip with confidence: "left eye" stays "left eye", not "right eye after horizontal flip".You enforce the label swap by hand on every flip and symmetry transform, and you find out you got it wrong from a confused model.
Medical, remote sensing, hyperspectral, multi-sensor dataAugment 4-, 9-, n-channel data at speeds that do not bottleneck the data loader.You either drop to single-channel paths and lose information, or you eat the multichannel slowdown.
Video-heavy preprocessingUse video- and batch-aware kernels for the volumetric cases instead of a per-frame loop.You roll your own per-frame loop or accept the slow path.
Teams with strict debugging and reproducibility needsCapture the exact sampled parameters per sample and replay any augmented batch deterministically.You guess from declared parameter ranges and hope the seed reproduces, while writing your own inspection layer against every transform.
Pipelines that carry metadata with imagesCarry captions, camera intrinsics, sensor calibration, and confidence maps through the pipeline as first-class targets that augmentation can update per transform.You wrap every transform with bookkeeping code or fork Compose per project.

Supply-Chain Security and Deployment Reliability

For teams that must audit or attest their dependency chain, these are the artifacts you can point at:

  • OIDC trusted publishing (no long-lived PyPI API tokens).
  • SBOM generation with SHA-256 checksums for every release asset.
  • Reproducible builds via committed lockfile.
  • A formal SECURITY.md with disclosure process and SLAs.
  • SPDX-format license metadata in pyproject.toml for accurate license detection by SBOM tooling.
  • OpenCV as an explicit optional dependency rather than an implicit heuristic-driven install.
  • Selectable resize backends (opencv, pillow, pyvips).

Without these, your compliance team has to either pin a frozen package or sign off on an unsupported dependency. Neither is a good option for software that ships to customers or runs production inference.

What You Get

Train rotated object detectors directly

Pad, crop, rotate, mosaic, and the full transform set operate on rotated boxes natively, in either the standard polygon format or cxcywh. Rotated detection is part of your pipeline, not a wrapper around it.

Without this, you implement and maintain rotated-bbox geometry for every transform you need — the standard outcome being "we shipped axis-aligned and pretended" or "we wrote a thousand lines of OBB code we now have to test."

Flips and symmetry preserve semantic keypoint meaning

Horizontal flip, vertical flip, D4, and square-symmetry transforms automatically remap semantic keypoint labels — left eye stays left eye, left hand stays left hand — so the augmented sample still matches the supervision contract.

Without this, every flip silently corrupts left/right pose labels. The model trains on inconsistent supervision and the bug shows up as "the pose model cannot decide which side is which."

Instance segmentation and pose pipelines stay aligned

Masks, bounding boxes, and keypoints stay aligned per object across the entire pipeline. When a crop drops an instance, its mask plane and keypoints are removed in lockstep. Mosaic and copy-paste augmentation preserve the same alignment.

Without this, masks, bounding boxes, and keypoints are independent arrays. Removing an instance via bbox filtering leaves the corresponding mask plane and keypoints behind — the canonical source of silent supervision corruption in instance and pose pipelines, often discovered months later as "the model is bad at small objects."

Carry your own metadata through the pipeline

Pass captions, camera intrinsics, sensor calibration, confidence maps, or any project-specific structure through Compose as first-class targets. Augmentation can update them per transform, and you can extend Compose with custom targets for project-specific data without forking it.

Without this, every team-specific target turns into a wrapper around every transform — code you write once and debug forever.

Augmentation is debuggable

You can ask "what exactly happened to this sample?" and get the concrete sampled values back, then replay them deterministically. Inspect failed samples, decide whether a sampled variant is realistic for your deployment domain, and reproduce the exact transformation later.

Without this, debugging a bad batch means guessing from declared parameter ranges and hoping the same seed reproduces. You also write the inspection layer yourself, against every transform.

3D volumes and YOLO-style letterboxing

3D-aware transforms operate on volumes, 3D masks, and keypoints together. Letterboxing — the standard scale-to-fit-with-padding step in YOLO-style pipelines — works across images, masks, horizontal and rotated boxes, keypoints, and volumes from a single transform.

Without these, you re-implement volumetric augmentation per project and you maintain a custom letterbox that handles your annotation types correctly.

More transforms

Dithering, AtmosphericFog, ChannelSwap, FilmGrain, Halftone, LensFlare, Vignetting, GridMask, WaterRefraction, CopyAndPaste, PixelSpread, ModeFilter, Enhance, Colorize — all maintained, tested, and benchmarked alongside the rest of the library, with full target propagation across images, masks, bounding boxes, and keypoints.

Without these, each is a transform you implement, test against bbox / mask / keypoint propagation, and maintain.

Performance

All speedup numbers below come from the public comparison at AlbumentationsX vs Legacy Albumentations. The benchmark code and output artifacts are public at albumentations-team/benchmark. You can rerun the comparison on your own hardware.

Multichannel

On 9-channel data, AlbumentationsX runs faster than the legacy package on 62 / 67 transforms, with a median speedup of 1.45x. Headline numbers:

If your workload is hyperspectral, medical, remote sensing, or anything with more than three channels, this is the strongest signal on the page. Full multichannel comparison table.

RGB geometry and distortion

The speedups concentrate on the transforms that dominate augmentation cost once you move past flips and crops:

Full RGB comparison table.

Video

On video transforms, AlbumentationsX is ahead on 59 / 89 head-to-head against the legacy package:

Full video comparison table.

Get Started

pip install albumentationsx

For licensing details, see the License Guide.

Sources