AugLy: Meta's data augmentation library for audio, image, text and video

The problem AugLy targets: augmentations that imitate internet platforms

Most augmentation libraries generate variations that a camera or a sensor might produce: crops, flips, colour jitter, noise. AugLy starts from a different premise. The README says the library was designed to include "many specific data augmentations that users perform in real life on internet platforms like Facebook's", and lists turning an image into a meme, overlaying text or emojis, and reposting a screenshot from social media as examples.

That framing decides who the library is for. If you are training an image classifier on photographs, the meme and screenshot transforms are noise you will never call. If you are building copy detection, hate speech detection, or copyright infringement models, they are the distribution shift your model actually faces, and generic geometric augmentation does not cover it. The README names those three problem areas explicitly and points to SimSearchNet, a near-duplicate detection model, as a real deployment.

The library covers four modalities: audio, image, text and video, each in its own sub-library under augly/. The README describes over 100 augmentations in total, with both function-based and class-based transforms, composition operators, and optional metadata about the transform and its intensity. That metadata is the part worth noticing: it lets you record which augmentation was applied at what strength, which matters when you want to measure robustness against a named transformation rather than just train on augmented data.

How the sub-libraries and extras are wired together

AugLy is a single PyPI package, augly, that ships four independent sub-libraries. The dependency split is not cosmetic. setup.py reads a top-level requirements.txt and then a separate requirements.txt inside each of augly/audio, augly/image, augly/text and augly/video, and builds extras_require from those files. The base install therefore carries only the shared dependencies: dataclasses-json, iopath, python-magic, regex and setuptools.

One line in setup.py is worth reading before you plan an install. The video extra is extended with the audio and image extras, so installing augly[video] pulls in the audio and image dependency sets as well. That is a deliberate consequence of video augmentations needing to manipulate frames and audio tracks, but it means the video install is the heaviest single-modality option and the one most likely to hit a native dependency problem.

The all extra is computed as the union of every modality's requirements, deduplicated through a set comprehension. There is no separate pinned lockfile in the repository root, so the resolution you get depends on the version ranges in those requirements files at install time.

Metadata generation runs through dataclasses-json, and file type detection through python-magic, which wraps libmagic. That last dependency is the one the README warns about, and it is the most common reason a fresh install fails on a machine without the system library present.

Installing AugLy and running a first augmentation

AugLy is a Python 3.6+ library. The README gives the full install as a single pip command with the all extra:

pip install augly[all]

If you only need one modality, install that extra instead. The README uses audio as the example:

pip install augly[audio]

The README notes that in some environments pip does not install python-magic as expected. In that case you install it separately, either through conda or through the system package manager:

conda install -c conda-forge python-magic

sudo apt-get install python3-magic

To run the unit tests or contribute, the README recommends cloning and installing in editable mode, optionally inside a fresh conda environment:

git clone [email protected]:facebookresearch/AugLy.git && cd AugLy
conda create -n augly && conda activate augly && conda install pip
pip install -e .[all]

For a first real use, the repository ships four Colab notebooks under examples/, one per modality: AugLy_audio.ipynb, AugLy_image.ipynb, AugLy_text.ipynb and AugLy_video.ipynb. Each sub-library README links to its own notebook, and the image one is linked directly from the top-level README. Open the notebook for the modality you installed and run its cells; that is the fastest way to see which augmentations exist and what arguments they take, because the per-modality READMEs carry the usage detail and the top-level README does not enumerate the transforms.

If you are coming from augly<=0.2.1, note the backwards compatibility change the README records: dependencies were not separated by modality before that split, so older instructions used pip install augly for most dependencies and pip install augly[av] for audio or video.

Where AugLy is the wrong tool

The clearest limitation is release cadence. The most recent release listed is v1.0.0 from 2022-03-29, preceded by v0.2.1 in December 2021 and v0.1.10 in October 2021. The repository's last push was on 2026-09-21 and it is not archived, so work is happening on main, but no tagged release has followed v1.0.0. If your project needs a versioned dependency with a changelog you can diff between upgrades, you are pinning to a release that is several years old and tracking main if you want anything newer.

The second limitation is dependency weight and fragility. python-magic is a hard requirement in the base install, and the README devotes a troubleshooting paragraph to it because it fails often. On a machine without libmagic you get an import error before you reach any augmentation code. Installing augly[video] compounds this by dragging in the audio and image stacks.

The third is scope. AugLy's distinguishing transforms assume internet-platform distortion. If your data comes from a controlled capture pipeline, the meme overlay, screenshot template and emoji overlay augmentations are inapplicable, and you are left with the more generic transforms that other libraries also provide, at the cost of a heavier dependency tree. The README is explicit that the library is "particularly useful" for copy detection, hate speech detection and copyright infringement, which is a statement about where it fits, not a claim that it fits everywhere.

Finally, the README does not document a rollback or downgrade procedure between the pre-0.2.1 and post-0.2.1 dependency layouts. If you inherit code written against the old extras, the migration is described in one sentence and nothing more.

AugLy compared with Albumentations and torchvision transforms

Albumentations is the reference point most people reach for, and the difference is one of premise rather than quality. Albumentations targets image-only pipelines and is built around fast geometric and photometric transforms applied to arrays, with a large catalogue of standard operations. AugLy spreads across four modalities and spends its distinctiveness on platform-specific transformations: overlay_onto_screenshot, which uses the screenshot templates in augly/assets/screenshot_templates/, is the clearest example, and it exists in both the image and video libraries.

The practical consequence is that the two libraries answer different questions. If you want to increase the effective size of an image training set with transformations that preserve the semantics of a photograph, Albumentations covers that ground and AugLy's extra weight buys you little. If you want to know how a model behaves when an image has been turned into a meme or a reposted screenshot, AugLy provides that transform and Albumentations does not.

AugLy also differs in how it reports what it did. The README states that transforms can optionally return metadata about the transform applied, including its intensity. That is useful when you want to attribute a robustness failure to a named transformation rather than to augmentation in general.

The assets themselves carry separate terms. The emojis are Twemoji, with graphics under CC-BY 4.0 and code under MIT. The fonts are Noto, published under the SIL Open Font License 1.1. The screenshot templates were created by a designer at Facebook specifically for AugLy. If you redistribute generated data, those asset licences travel with it.

Licence, maintenance and upgrade cost

The repository's LICENSE file is MIT, and setup.py declares the classifier "License :: OSI Approved :: MIT License". The GitHub metadata reports the licence as NOASSERTION, which reflects that the platform could not classify the file automatically rather than a different licence. The README adds a caveat worth reading in full: some of the dependencies AugLy uses may be licensed under different terms. That caveat is about your dependency tree, not about AugLy's own code, and it is the reason the asset and dependency licences above matter. This is a description of what the repository states, not legal advice.

Upgrade cost is dominated by the release gap. With v1.0.0 from 2022-03-29 as the newest tag, an upgrade means moving from one tagged release to whatever is on main, and the README documents no changelog or migration guide beyond the pre-0.2.1 dependency note. If you install with pip install augly[all], your dependency versions come from the ranges in the requirements files, so two installs at different times can resolve differently without any AugLy release in between.

The dependency split does reduce upgrade exposure in one direction: if you only use the text sub-library, installing augly[text] keeps the audio, image and video dependency sets out of your environment entirely, so their version churn never reaches you.

Editorial conclusion

Adopt AugLy if your problem involves media that has passed through a social platform: memes, reposted screenshots, overlaid text, re-encoded audio. Skip it if you need a maintained augmentation pipeline for standard supervised training, since the last release was v1.0.0 on 2022-03-29 and the README does not document a migration path. Before committing, install the single modality extra you need and check that python-magic resolves in your environment, because that is the failure the README calls out first.

Frequently asked questions

Official sources

1. facebookresearch/AugLy on GitHub
2. Issues
3. Project website
4. README
5. Releases