TextAttack: named attack recipes, one cache directory, and a docs-check target that duplicates docs

Four jobs, one command, and two entry points

The README gives four reasons to use the framework and they are four different jobs rather than one: understanding models better by running attacks against them and reading the output, researching and developing new attacks with a library of components, augmenting a dataset to improve generalisation and robustness downstream, and training a model with a single command including all downloads. The interface is one command with subcommands, of which two are called common, one to run attacks and one to augment. Every command takes a help flag, and the whole tool can be invoked either as a console script or as a Python module:

pip install textattack

The examples directory is split four ways to match those jobs, with separate folders for attacks, augmentation, datasets and training, including a script for augmenting a spreadsheet file.

A recipe is four components, and the table is the documentation

The most useful page in the README is the recipe table, because it defines each published attack as a tuple of four things rather than as a name you have to look up. Each row names the goal function, the constraints enforced, the transformation and the search method. Reading the first rows makes the structure obvious: one attack combines untargeted classification with constraints on the percentage of words perturbed, word embedding distance, sentence encoding similarity and part of speech consistency, applies either a counter-fitted embedding swap or masked token prediction, and searches greedily by gradient. Another applies the same kind of transformation with a genetic algorithm as the search. Recipes are listed with a dedicated list command and run by name, which means you can enumerate what exists before deciding which one to reproduce.

Everything downloaded lands in one directory you can move

The setup section has a tip that matters more than it looks. TextAttack downloads files to a cache directory in your home folder by default, and that includes pretrained models, dataset samples and the configuration file itself. To change it you set an environment variable, and the example given sets it to a temporary path before running an attack. Two consequences follow. First, a container or a shared machine can be pointed at a volume instead of a home directory, which is the difference between a cache that persists across runs and one that re-downloads a model each time. Second, because the configuration file sits in the same place, anything you change there is as versionless as everything else, so the cache is part of your environment rather than part of your repository.

Two flags change the shape of a run: --parallel and --interactive

Most of the command line surface is one flag at a time and the flags are additive, but two of them change what the tool is doing rather than how it looks. The parallel option distributes an attack across multiple GPUs, and the README is specific that this can really help performance for some attacks, while pointing at a separate example script for attacking Keras models in parallel, which suggests that path needed different handling. The interactive flag replaces the dataset and the example count with samples typed by the user, which turns the tool into a probe you drive by hand. Both are worth knowing before you launch a long run, because discovering either one afterwards means throwing the run away.

The release gap is two years, and the version number lives in the docs config

Three releases are visible in the history and the spacing between them is the story. The most recent is version 0.3.11, published in August 2026, and before it came 0.3.10 in March 2024 and 0.3.9 in September 2023, so there is a gap of more than two years between the middle and the newest tag, with the last commit on the default branch dated 15 August 2026, the day before that release. The packaging explains where the number comes from: the setup file does not carry a literal version at all, it imports the release value from the documentation configuration module, with a comment saying the version is tracked there. So the version of an installed package is defined by a file inside the docs build, which is unusual and worth knowing if you script anything against it.

The base requirements pull in a sequence labeller and Chinese NLP tooling

The dependency list is longer than a targeting library needs, and reading it tells you what the framework does beyond running attacks. There is a sequence labelling library in the base requirements rather than in an extra, along with a grammar checking package, an inflection library, an edit distance package, a semantic similarity score, and two Chinese language packages plus a dictionary resource for Chinese word segmentation and pinyin. The deep learning stack is the expected pair, with a minimum version on the tensor library, an explicit exclusion of one specific early version, and a minimum on the transformer library that is far newer than the Python floor the README states. Optional extras exist for sentence embeddings, a linguistic annotation toolkit, two experiment trackers and topic modelling, and there is a separate extra for the tensor flow stack.

The docs-check target runs the same command as docs

The Makefile is a small tour of the toolchain and contains one bug worth reporting. Formatting runs three tools in sequence, with the import sorter in atomic mode over the test and package directories and a docstring formatter over both. Linting runs the same formatter in check mode, the sorter in check mode, and a style checker with a hard coded list of ignored codes and a directory exclusion. Tests run under pytest with distribution by file and as many workers as the machine has. Then there are the documentation targets: one builds the HTML, one is supposed to build it and exit with an error code rather than a warning, and one runs a live reload server on a fixed port. The problem is that the first two targets contain the identical command, so the stricter one does nothing extra.

Editorial conclusion

TextAttack suits a research or applied NLP team that wants to reproduce published attacks against its own models, or to use adversarial examples as augmentation, without writing the search loop by hand. It does not suit a production service that needs a small dependency footprint, because the base requirements pull in a sequence labelling library and a set of linguistic tooling packages, and several of the extras are pinned to old versions. Three things to check before you build a pipeline on it: which recipe matches the attack in the paper you are reproducing, since the table is the only definition of what each one enforces; whether your hardware will make the run bearable, since a GPU is called optional but said to greatly improve speed and there is a flag for spreading an attack across several; and where the cache goes, since models and dataset samples are downloaded by default into a single directory in your home folder.

Frequently asked questions

Official sources

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