Guide · Open source
How to use imgaug: install and augment images for ML
Updated · written with AI from the project's own documentation and checked against our catalogue data
imgaug is an open-source Python library for image augmentation in machine learning projects. It takes a set of input images and produces a larger set of slightly altered copies, such as rotated, cropped, noisy or recolored versions, to expand a limited training dataset. This guide explains what it does, how to get the code, what it supports and when another tool may fit better.
imgaugaleju/imgaug · ★ 14.7k · MIT Install options & downloads Quick start
- 1Check your Python version. Confirm that your Python version is covered by the README, which states support for 2.7 and 3.4+. Verify compatibility for newer versions yourself.
- 2Get the source. Clone the repository with git clone https://github.com/aleju/imgaug.
- 3Read the installation section. Follow the README's installation section for your environment, including the Anaconda option it describes.
- 4Check your data types. Use uint8 images for full support, and read the dtype support documentation for other types.
- 5Choose augmentations. Pick the augmentation types that suit your task, such as affine, crop and pad, or noise and contrast changes.
- 6Apply to images and annotations together. Pass your images along with their segmentation maps, keypoints or bounding boxes so they are transformed together.
- 7Consult the documentation. Use imgaug.readthedocs.io for API details and examples as you build your pipeline.
What imgaug does and who it is for
imgaug converts a set of input images into a new, much larger set of slightly altered images. The augmented copies are meant to be used as extra training data for machine learning models.
It also transforms matching annotations, such as segmentation maps, keypoints and bounding boxes, so they stay aligned with the changed images. This matters when your labels are tied to positions in the image.
- Machine learning engineers training image models on a limited dataset
- Researchers who need augmentations that keep bounding boxes or keypoints aligned
- Developers building Python image pipelines who want many augmentation types in one library
Get the imgaug code
The project is hosted on GitHub under the aleju organisation. The README's installation section describes the supported setup, including an Anaconda option. Read the full installation section on the repository page for the steps that apply to your environment, since this summary includes only the clone command.
Check your Python version before you install. The README states support for Python 2.7 and 3.4+, and it does not say which newer versions are supported, so confirm compatibility for your version yourself.
- Python: the README mentions 2.7 and 3.4+; check current compatibility for newer versions
- Clone the repository from GitHub using the command below
git clone https://github.com/aleju/imgaugKnow which data types imgaug can augment
imgaug supports several kinds of data alongside images. Heatmaps are float32, segmentation maps are int, and masks are bool. Keypoints, bounding boxes, polygons and line strings are supported with int or float coordinates.
Images have full support for uint8. For other image dtypes, the project documentation has a separate dtype support page. Heatmaps and segmentation maps may be smaller or larger than their images, and the README says no extra lines of code are needed for an operation such as a crop.
- Images: full support for uint8
- Heatmaps (float32), segmentation maps (int), masks (bool)
- Keypoints, bounding boxes, polygons and line strings (int or float coordinates)
Choose which augmentations to apply
The README lists many augmentation techniques, including affine transformations, perspective transformations, contrast changes, Gaussian noise, dropout of regions, hue and saturation changes, cropping and padding, and blurring. The example grid in the README shows groups such as non-geometric changes, affine, crop and pad, and horizontal flip with perspective.
You can apply augmentations only to some images, and you can apply them in random order. Parameters can be fixed values or probability distributions. The README gives examples such as rotating images by values sampled from a uniform range from -10 to 45 degrees.
- Affine and perspective transformations
- Contrast, Gaussian noise, hue and saturation changes
- Cropping, padding, blurring and region dropout
- Random order and per-image selection of augmentations
Keep labels aligned with the changed images
When a random value is sampled, imgaug applies the same value to the image and its annotations. The README gives an example: an image and its segmentation map are rotated by the same sampled value, with no extra lines of code.
The library also includes helper functions. The README mentions drawing heatmaps, segmentation maps, keypoints and bounding boxes, scaling segmentation maps, pooling images and maps, padding images to a target aspect ratio such as square, and converting keypoints to distance maps.
- Same sampled value applied to images and matching annotations
- Helpers to draw and scale maps, pool images, and pad to aspect ratio
- Support for augmentation across multiple CPU cores
Check the documentation and troubleshoot problems
The README links to the full documentation at imgaug.readthedocs.io, which covers the API and the dtype support page. The example images and code examples in the README are the best starting point for seeing what each operation does.
If an install or run fails, first confirm your Python version against the README's stated support for 2.7 and 3.4+ and check the installation section for your setup. If your data is not uint8 images, check the dtype support documentation before you run augmentations.
- Documentation: imgaug.readthedocs.io
- Dtype support: see the documentation page on dtype support
- Python version: confirm compatibility before installing
What people use it for
- Expanding a small labelled image dataset before training a classifier
- Augmenting images with bounding boxes so object locations stay correct after rotation or cropping
- Transforming segmentation maps and masks alongside their source images
- Applying random crops, padding and flips across many images in one Python pipeline
Frequently asked questions
Is imgaug free to use?
The source lists imgaug under the MIT licence. Check the LICENSE file in the repository for the full terms before using it in your project.
What Python version do I need for imgaug?
The README states support for Python 2.7 and 3.4+. It does not confirm newer versions, so check current compatibility before installing.
How do I install imgaug?
The README's installation section describes the supported methods, including Anaconda. The only command in this summary is git clone https://github.com/aleju/imgaug, so follow the full installation section for the remaining steps.
Does imgaug move bounding boxes and keypoints with the image?
Yes. The README says imgaug transforms segmentation maps, keypoints and bounding boxes so they stay aligned with the changed images. It applies the same sampled random values to the image and its annotations.
What are good alternatives to imgaug?
The project lists albumentations, torchvision transforms and Augmentor as comparable projects. For a simple flip or rotation, the README suggests OpenCV or torchvision may be lighter.
Why is my augmentation not working with my image data?
Images have full support for uint8 in imgaug. For other dtypes, check the dtype support documentation at imgaug.readthedocs.io before running augmentations.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
imgaug suits machine learning engineers and researchers who need many augmentation types in Python and need labels such as bounding boxes or keypoints to stay aligned with images. If you only need a simple flip or rotation, or you work outside Python, a lighter option such as OpenCV, torchvision or another listed alternative may be a better fit.
Install options & downloads