Install & Compatibility
Where this runs
tested against v1.1.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.813s · 173.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.2s · import 1.739s · 166MB
174MB installed
● package 174MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KeyboardAug
✓ from nlpaug.augmenter.char import KeyboardAug
SynonymAug
✓ from nlpaug.augmenter.word import SynonymAug
ContextualWordEmbsAug
✓ from nlpaug.augmenter.word import ContextualWordEmbsAug
RandomSentAug
✓ from nlpaug.augmenter.sentence import RandomSentAug
Sequential
✓ from nlpaug.flow import Sequential
DownloadUtil
✓ from nlpaug.util.file.download import DownloadUtil
This quickstart demonstrates character-level augmentation using KeyboardAug. It initializes an augmenter to simulate typos by replacing characters with nearby keys on the keyboard. The `augment` method returns a list of augmented texts, even if `n=1` (default).
import nlpaug.augmenter.char as nac
text = "The quick brown fox jumps over the lazy dog."
# Initialize a Keyboard Augmenter
# Simulates typos based on keyboard proximity
aug = nac.KeyboardAug(aug_char_p=0.1, aug_word_p=0.1, aug_char_min=1)
# Augment the text
augmented_text = aug.augment(text)
print(f"Original: {text}")
print(f"Augmented: {augmented_text[0]}")
Debug
Known issues
gotchaMany augmenters require external model or data downloads (e.g., NLTK data for SynonymAug, pre-trained word embeddings for WordEmbsAug, or transformer models). These are not automatically installed with the base package.fixUse `nlpaug.util.file.download.DownloadUtil.download_xxx()` for models (e.g., word2vec, GloVe) and `nltk.download('wordnet')`, `nltk.download('omw-1.4')` for NLTK data before initializing the respective augmenters. affects: All versions
breakingThe `augment()` method's output format changed from a single string to a list of strings when `n > 1` (default `n=1`) in version 0.0.9. Code expecting a direct string might break.fixAlways treat the output of `augment()` as a list. If only one augmented output is expected, access it via `augmented_text[0]`.
affects: <0.0.9
deprecatedSeveral augmenter classes and parameters have been deprecated or replaced. For example, `WordNetAug` was replaced by `SynonymAug`, `QwertyAug` by `KeyboardAug`, and the `aug_n` parameter by `top_k`.fixConsult the official documentation for the latest API and use the recommended replacement classes and parameters.
affects: >=0.0.7 (QwertyAug, StopWordsAug), >=0.0.9 (WordNetAug, aug_n parameter)
gotchaPerformance of transformer-based augmenters (e.g., `ContextualWordEmbsAug`, `ContextualWordEmbsForSentenceAug`) can be slower than expected, especially with older `transformers` library versions or large `n` values.fixEnsure `nlpaug` and `transformers` are updated to their latest versions for performance optimizations. Consider reducing `n` (number of augmented samples) or using batching for large datasets if performance is critical.
affects: All 1.x versions (performance improvements rolled out in 1.1.9, 1.1.10)
gotchaCompatibility issues with underlying libraries, particularly `transformers` and `torch`, have been observed. Specific versions may be required for certain augmenters to function correctly.fixPin `transformers` and `torch` versions as recommended in `nlpaug`'s GitHub README or installation guides. Updating `nlpaug` to the latest version often includes compatibility fixes.
affects: All 1.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nlpaug'
The nlpaug library is not installed or the Python environment where it's installed is not activated. Sometimes, a script named 'nlpaug.py' in the current directory can shadow the installed package.
fixEnsure nlpaug is installed with `pip install nlpaug`. If already installed, check your Python environment or rename any local script named `nlpaug.py`.
AttributeError: module 'nlpaug.augmenter.word' has no attribute 'BertAug'
The 'BertAug' class has been deprecated in newer versions of nlpaug. It was replaced by 'ContextualWordEmbsAug'.
fixReplace `BertAug` with `ContextualWordEmbsAug` in your code. For example, `from nlpaug.augmenter.word import ContextualWordEmbsAug`.
AttributeError: 'DataFrame' object has no attribute 'strip'
NLPAug augmenters expect a string or a list of strings as input, but a Pandas DataFrame object was passed directly.
fixExtract the text data from the DataFrame column as a list of strings before passing it to the augmenter. For example, `augmented_text = aug.augment(df['text_column'].tolist())`.
RuntimeError: DataLoader worker (pid(s) XXXX) exited unexpectedly
This error often occurs when using `BackTranslationAug` and can be related to issues with multiprocessing, insufficient memory, or an incorrect input format (e.g., passing a single string instead of a list).
fixEnsure the input to `BackTranslationAug.augment()` is a list of strings, even for a single sentence. Additionally, try setting a smaller `batch_size` during augmenter initialization, or ensure you have enough memory. Example: `back_translation_aug = BackTranslationAug(..., batch_size=2)`.
ValueError: Sample larger than population or is negative
This error typically occurs when an augmentation operation attempts to sample more elements than are available in the input or a defined subset, often seen with augmenters that randomly select words or characters.
fixAdjust the augmentation parameters such as `aug_word_max`, `aug_char_max`, or `aug_p` to ensure they do not exceed the possible number of elements to be augmented or the length of the input text.
Upgrade
Version history
1.1.11latest on PyPI · released Jul 7, 2022
Audit
Dependencies
numpyrequiredCore dependency for numerical operations, including basic installation.
requestsrequiredCore dependency for network requests, including basic installation.
torchoptionalRequired for transformer-based augmenters like ContextualWordEmbsAug, ContextualWordEmbsForSentenceAug, and AbstSummAug.
transformersoptionalRequired for transformer-based augmenters like ContextualWordEmbsAug, ContextualWordEmbsForSentenceAug, and AbstSummAug.
sentencepieceoptionalRequired for some transformer models used in contextual augmenters.
simpletransformersoptionalRequired for LambadaAug.
nltkoptionalRequired for AntonymAug and SynonymAug (uses WordNet).
gensimoptionalRequired for WordEmbsAug (word2vec, GloVe, fastText models).
librosaoptionalRequired for audio augmenters like PitchAug, SpeedAug, and VtlpAug.
matplotliboptionalRequired for audio augmenters (specifically for visualizations or certain audio processing, if used with librosa).