EasyJailbreak: a component framework for LLM jailbreak research

Six steps instead of one script that sends a prompt

EasyJailbreak is a Python framework for researchers and developers focused on LLM security, and its central idea is decomposition. Rather than shipping a single attack, it breaks the mainstream jailbreaking process into a sequence of iterable steps: initialize mutation seeds, select suitable seeds, add a constraint, mutate, attack, and evaluate. A component exists for each step, and the project describes the result as a playground for further research.

The audience is specific. This is for people measuring how well a model holds its safety behaviour, or comparing attack recipes against one another, not for shipping an assistant. The project topics reflect that framing, listing llm-safety-benchmark, llm-security and discrete-optimization alongside jailbreak.

The design consequence is worth stating plainly: because the pipeline is assembled from parts, you can read a recipe as a table of choices. A paper, a benchmark write-up and a reproduction script then describe the same thing in three different notations, which is not something a collection of standalone attack scripts can offer.

The mutation and inference loop is the unit that does the work

The project structure is described in three parts. The first asks the user to prepare queries, configuration, models and seeds. The second is the main part, two processes that form a loop. The third is the report the user receives when the loop stops.

Inside the loop, the mutation process selects the best prompts through the Selector, transforms them through the Mutator, and filters the results through the Constraint. The inference process then sends those prompts at the target model, takes the responses, and feeds them to the Evaluator, which produces a score for the round. That score goes back to the Selector, which completes one cycle.

The important detail is that the Selector consumes the Evaluator's score. Mutation is not a blind random walk over prompt transformations; it is a search that is steered by how well previous attempts scored, which is why the selector implementations include MCTSExploreSelectPolicy, EXP3SelectPolicy and UCBSelectPolicy alongside RandomSelector and RoundRobinSelectPolicy.

Recipes differ mainly in which mutators and evaluator they wire in

The four essential components are Selectors, Mutators, Constraints and Evaluators, and each recipe fills the table differently. That table is the most compact description of the framework's coverage.

ReNeLLM uses a mutator set covering style change, insertion of meaningless characters, misspelling sensitive words, rephrasing, generating similar prompts and altering sentence structure, with DeleteHarmLess as its constraint and a generative judge as evaluator. GPTFuzz is the opposite shape: no constraint, but the widest selector menu in the table, spanning Monte Carlo tree search exploration, random, EXP3, round robin and UCB policies, with mutators such as expand, rephrase, crossover, translation and shorten, and a classification judge to score results.

Other recipes go further down the pipeline. ICA and AutoDAN list no selector, mutator or constraint at all, so they run a fixed attack and rely on a pattern judge to decide success. PAIR uses a single mutator, HistoricalInsight, with a generative score evaluator. JailBroken is a mutator list in itself, covering obfuscation, payload splitting, several base64 variants, leetspeak and rot13.

Reading across the columns also shows where the framework is thin. Most recipes leave constraint and selector unused, so the compositional machinery is exercised unevenly across the attack strategies it supports.

Installing from PyPI or running from a clone for new components

Both installation routes need Python 3.9 or later. The first route is for users who only want the approaches already collected in the project.

pip install easyjailbreak

The second route is for anyone who intends to add new components, such as a new mutate or evaluate method.

git clone https://github.com/EasyJailbreak/EasyJailbreak.git
cd EasyJailbreak
pip install -e .

The editable install matters more than it looks. The packaging metadata declares the distribution as easyjailbreak at version 0.1.3, finds packages under the easyjailbreak namespace, and lists an Alpha development status in its classifiers. Editing in place is the supported path for extending the framework, and the repository ships a tutorial directory alongside the examples folder, where scripts exist for individual recipes including PAIR, TAP, AutoDAN, cipher, GCG, GPTFuzzer, ICA, JailBroken, ReNeLLM and others.

A heavy dependency set for a framework that calls hosted models

The dependency list is where the practical cost shows up. It includes transformers>=4.34.0, torch>=2.0, datasets, accelerate, protobuf, sentencepiece, numpy, pandas, einops, nltk, jsonlines, openai>=1.0.0 and fschat, plus a transformers_stream_generator entry in setup.py.

Two details are easy to miss. The first is fschat: requirements.txt fixes it to fschat==0.2.34, while setup.py lists 'fschat' with no version constraint, so the two files disagree and a pip install from the registry can resolve differently from the repository environment. The second is that heavy local inference dependencies sit next to an openai client dependency, which suggests the framework mixes local model serving with hosted endpoints. Anyone with a Python 3.9 to 3.11 environment and a constrained disk should expect a long install and possible solver conflicts around torch.

The dependency set also explains why the framework is convenient for evaluation work. Judges such as Evaluator_GenerativeJudge and Evaluator_GenerativeGetScore need a capable model behind them, and Evaluator_PatternJudge does not, which is what makes the pattern based recipes cheap to run.

Reports, stopping mechanisms and the choice of an evaluator

The output of a run is a report. Under some stopping mechanism the loop ends and the user receives a report on each attack, including the jailbreak prompts, the responses from the target model and the evaluator's scores. The documentation does not enumerate the available stopping mechanisms, so the number of rounds, the score threshold and the maximum budget are things you will have to read in the API documentation or set yourself.

The evaluator choice shapes what a report means. A pattern judge scores a response by matching known output patterns, which is cheap and deterministic but only knows what it was told to look for. A generative judge asks a model whether the response complies with the harmful request, which tracks open-ended behaviour better but adds model calls and its own disagreement between runs. A classification judge sits in between, producing a label rather than a score.

For a benchmark, that choice is not a detail. Two recipes with different evaluators are not comparable, and the recipes in the table mix evaluator types freely, so results across recipes should be read with the evaluator column in view.

Code moved in 2026 while the last release stayed on 0.1.3

The maintenance picture needs two dates to read correctly. The last push was on 2026-09-01, so the repository is receiving work. The most recent tagged release is 0.1.3 from 2024-08-30, with earlier tags at 0.1.2 and 0.1.1, and setup.py still declares version 0.1.3. In other words, the branch is moving and the published version has not moved with it, so a pip install gives you the 2024 state of the code while a clone gives you something else.

That gap is the practical upgrade risk for a research tool. Recipes can change behaviour between a tag and the branch head, and a benchmark written today may not reproduce on the released version without checking which one produced the numbers.

The licence is GPL-3.0, declared in setup.py and stored in the LICENSE file at the repository root. That matters more than usual for a framework people extend: adding your own mutator or evaluator in a fork or an in-house copy brings copyleft obligations on the distributed result. This is a note about the terms rather than advice, and teams embedding the code should read the licence themselves.

Editorial conclusion

Adopt EasyJailbreak when your team runs repeatable red teaming against hosted models and needs to compare attack strategies or score results with a consistent judge. Do not adopt it for a one-off attack, because the dependency set includes torch and model provider SDKs for work a single script does not need. Before the first install, confirm that Python 3.9 or later is present, decide whether the judges will run against a local model or a hosted endpoint, and check the pin on fschat, since requirements.txt fixes fschat==0.2.34 while setup.py lists fschat without a version, so a pip install easyjailbreak can resolve to a different release than the repository environment.

Frequently asked questions

Official sources

1. EasyJailbreak/EasyJailbreak on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases