nlpaug: text, audio and spectrogram augmentation for NLP pipelines

The gap nlpaug fills between a small labelled set and a model that generalises

Most NLP teams hit the same wall: a few thousand labelled sentences, a model that memorises them, and no budget for more annotation. nlpaug targets that gap by generating synthetic variants of existing text rather than collecting new text. The README frames the goal as generating synthetic data for improving model performance without manual effort, and the library also covers audio and spectrogram inputs, which is unusual for a package filed under NLP topics.

The audience is narrow but real. You are training a classifier, a tagger or a translation model, you already have a dataset, and you want more surface variety without changing labels. Character-level augmenters such as KeyboardAug and OcrAug simulate typing and scanning noise, which is what you want when your production input arrives from users or from document scans. Word-level augmenters such as SynonymAug and ContextualWordEmbsAug produce paraphrases that keep the label intact. Sentence-level augmenters such as ContextualWordEmbsForSentenceAug and AbstSummAug change the amount of text, not just its wording.

What nlpaug is not is a labelling tool or an active-learning loop. It cannot tell you whether an augmented example is still correctly labelled, and it does not filter low-quality generations except in the specific LambadaAug path, which the README describes as generating text with a language model and then using a classification model to retain high quality results. For every other augmenter, quality control is your job.

Augmenter and Flow: how a pipeline is actually assembled

The README states the architecture in one line: Augmenter is the basic element of augmentation while Flow is a pipeline to orchestrate multiple augmenters together. That split matters more than it first appears. A single augmenter owns one transformation and its parameters. A Flow owns the order in which transformations run and the probability that each one fires.

Augmenters are grouped by target and action. Textual augmenters operate at character, word or sentence granularity. Signal augmenters such as CropAug, LoudnessAug, MaskAug, NoiseAug, PitchAug and ShiftAug operate on audio, and the repository also ships a spectrogram example notebook. The action column in the README table distinguishes insert, substitute, swap, delete, split and crop, so you can reason about what an augmenter does to sequence length before you run it. Substitution keeps length stable. Insertion and deletion do not, which matters if your model expects fixed-size inputs.

The underlying mechanism differs per augmenter. SynonymAug and AntonymAug consult WordNet. WordEmbsAug uses word2vec, GloVe or fasttext vectors. ContextualWordEmbsAug feeds surrounding words to BERT, DistilBERT, RoBERTa or XLNet to pick a replacement. TfIdfAug uses TF-IDF weights to decide which word to change. BackTranslationAug runs text through two translation models. That variety is the point, and it is also the cost: each family has its own dependency and its own failure mode.

Installing nlpaug and running a first word augmentation

The README points to an Installation section and the repository ships a pyproject.toml, so the expected path is a normal pip install. The package declares requires-python >=3.12, which means a Python 3.12 interpreter is the floor, not a suggestion.

pip install nlpaug

The dependency list in requirements.txt is short: numpy, pandas, requests and gdown. Everything else is an optional extra. pyproject.toml defines extras for transformers, nltk, word-embs, audio, lambada and dev, so the transformer-backed augmenters and the WordNet-based synonym and antonym substitution each need their own extra installed before they will run.

The README lists a quick example notebook at example/quick_example.ipynb and a longer textual augmenter notebook at example/textual_augmenter.ipynb. Both show the pattern the library is built around: construct an augmenter, then call it on a string. Rather than restating the notebook, run it after installing the extras it imports, and check that the returned list contains a rewritten sentence rather than the original.

To chain several augmenters, wrap them in a Flow, which the README describes as a pipeline for orchestrating multiple augmenters together. The repository ships example/flow.ipynb for that, and example/change_log.ipynb for inspecting what an augmentation pass actually changed.

The repository also ships a Makefile with uv targets. Running make uv-sync sets up a virtual environment through scripts/setup_uv.sh, and make test runs the core test suite. Those targets exist for contributors working from a clone, not for consumers installing from PyPI.

Model downloads, extras and the cost of the transformer augmenters

The lightweight claim in the README applies to the core install, not to the whole library. ContextualWordEmbsAug needs torch, transformers and sentencepiece, all pulled in by the transformers extra. WordEmbsAug needs gensim through the word-embs extra. The audio and spectrogram augmenters need librosa and matplotlib through the audio extra. LambadaAug needs simpletransformers through its own extra, which is a heavier dependency chain than the others.

Beyond package size, several augmenters download pretrained weights at first use. The core dependencies include gdown, which is a Google Drive downloader, and the README has a dedicated Reference section for external resources such as data and models. That design means the first call to a contextual augmenter is a network operation, and an offline CI runner will fail unless the weights are cached or pre-fetched. The repository has an integration test marker described in pyproject.toml as covering tests that require external models, corpora or heavyweight optional dependencies, which confirms that these paths are treated separately from the core suite.

Version drift is the other cost. The published releases listed for the project stop at 1.1.11 from 2022-07-07, while pyproject.toml declares version 2.0.0 and requires Python 3.12. Anyone reading the release page and expecting a 2.0.0 changelog entry will not find one there. The last push to the repository was on 2026-09-08.

Where nlpaug is the wrong tool

The clearest limitation is the Python version floor. If your training environment is pinned to Python 3.11 or earlier, the 2.0.0 line will not install, and the README does not document a supported downgrade path for that case. You would be looking at the older 1.1.x releases instead, whose dependency expectations differ from what requirements.txt now lists.

A second limitation is label preservation. Substitution augmenters assume the label survives the rewrite, and that assumption breaks in classification tasks where a single word carries the decision. AntonymAug is explicitly built to substitute opposite-meaning words, so using it on sentiment or stance data will flip labels by construction. The README documents what each augmenter does; it does not document which tasks each one is safe for.

Third, deterministic reproduction is not free. Several augmenters sample from a language model or a random distribution, and the README does not state a seeding contract for the augmenters. If you need bit-identical augmented datasets across runs, you have to verify that yourself.

Finally, the audio and spectrogram side is gated behind an extra that many NLP-only environments will not install. Teams that want text augmentation only should not read the audio feature list as available out of the box.

nlpaug against TextAttack and TextAugment

TextAttack and TextAugment appear in the same search space as nlpaug, and they differ in intent rather than in feature count. TextAttack is built around adversarial attack and adversarial training workflows, which is why nlpaug carries adversarial-attacks and adversarial-example among its repository topics. The difference is direction: an attack recipe searches for the perturbation that most degrades a specific model, while an augmentation recipe generates plausible variants without reference to a model's current errors. If your goal is measuring or hardening a model against worst-case inputs, an attack framework matches the task. If your goal is enlarging a training set, nlpaug matches it.

TextAugment is the closer comparison, because it also generates augmented text. The structural difference visible in the repository is breadth. nlpaug exposes character, word and sentence augmenters plus audio and spectrogram augmenters behind a single Augmenter interface, and adds Flow for chaining them. A narrower augmentation package typically gives you one family of transformations and no composition layer. Whether that breadth helps depends on your pipeline: if you only ever need synonym substitution, the extra dependency surface of nlpaug's transformer and audio extras is cost without benefit.

Licence and the maintenance picture

nlpaug is MIT licensed, stated both in the repository and in the pyproject.toml license field. MIT is permissive: you can use, modify and redistribute the code, including in closed-source products, provided the copyright notice and licence text are retained. That is a summary of the licence text, not legal advice, and the practical question for most teams is whether the pretrained models some augmenters download carry their own licences. The README has a Reference section for external data and models, and those resources are separate from the MIT grant covering nlpaug's own code.

On maintenance, the facts are mixed and worth stating plainly. The repository is not archived, and the last push was on 2026-09-08. The most recent published release listed is 1.1.11 from 2022-07-07, while pyproject.toml declares version 2.0.0 and requires Python 3.12. The README also mentions a Python 3.12-ready V2 baseline with offline-first tests and GitHub Actions coverage. So the code is moving, but the release page and the version file are not in step, and a team that pins by release tag will get a different artifact than one that installs from the repository.

Upgrade cost follows from that gap. Moving from 1.1.x to the 2.0.0 line means moving to Python 3.12, and the core dependency floors are high: numpy >=2.4.6, pandas >=3.0.3, transformers >=5.9.0 in the transformers extra. Those are not incidental bumps, and a project sharing an environment with older ML tooling may not be able to satisfy them.

Editorial conclusion

Adopt nlpaug if you are on Python 3.12 or newer and want character, word, sentence or signal augmentation behind one Augmenter and Flow API, and you accept that transformer-backed augmenters pull in torch and transformers. Do not adopt it if you are pinned to Python 3.11 or earlier, since pyproject.toml declares requires-python >=3.12, and do not expect the audio or spectrogram augmenters to work without the audio extra. Verify first which extras your pipeline needs, then check that the pretrained model files each augmenter downloads are reachable from your build environment.

Frequently asked questions

Official sources

1. License: MIT
2. makcedward/nlpaug on GitHub
3. Project website
4. README
5. Releases