# CUPP Interactive Mode vs Dictionary Improvement Mode: Key Differences Explained

> Discover the key differences between CUPP interactive mode and dictionary improvement mode. Learn how interactive mode builds wordlists from scratch while improvement mode enhances existing ones.

- Repository: [Mebus/cupp](https://github.com/Mebus/cupp)
- Tags: deep-dive
- Published: 2026-07-01

---

**Interactive mode generates a custom wordlist from scratch by asking personal questions about a target, while dictionary improvement mode enriches an existing wordlist file with mutations, special characters, and leet-speak variations.**

CUPP (Common User Passwords Profiler) is an open-source password dictionary generator maintained in the Mebus/cupp repository. Understanding the difference between interactive mode and dictionary improvement mode in CUPP is essential for penetration testers who need to create targeted password lists. Each mode serves a distinct purpose in the profiling workflow, with separate entry points and output formats defined in the source code.

## How Interactive Mode Works in CUPP

### Entry Point and Core Implementation

When you invoke CUPP with the `-i` or `--interactive` flag, the script calls the `interactive()` function located in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) (lines 299-305). This function initiates a detailed questionnaire that personalizes the resulting wordlist to a specific target based on their personal information.

### Data Collection and Validation

The mode prompts for detailed personal information including **first name**, **surname**, **birthdate**, **nicknames**, **pets**, **company names**, and other target-specific details. Input validation occurs in real-time; for example, the birthdate must be exactly 8 digits (DDMMYYYY format) according to the validation logic in the source. This highly interactive process pauses for each question and validates inputs before proceeding.

### Generation Logic and Output

After collecting data, CUPP generates combinations including reversed strings, date fragments, special-character suffixes, and random numbers. If **leet-mode** is enabled, the script substitutes characters (e.g., 'a' becomes '@', 'e' becomes '3'). The final wordlist writes to a file named `<first-name>.txt`, derived directly from the victim's profile data provided during the session.

## How Dictionary Improvement Mode Works in CUPP

### Entry Point and Core Implementation

Dictionary improvement mode triggers when you supply the `-w <file>` argument, calling the `improve_dictionary()` function defined in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) (lines 777-783). Unlike interactive mode, this function requires an existing wordlist file as input and processes it algorithmically rather than collecting new intelligence.

### Mutation and Enhancement Process

This mode loads the supplied wordlist and splits it into individual words before applying transformations. It optionally **concatenates** every word with every other word, appends **special characters**, adds **random numbers**, and applies **leet-speak** substitutions. The process includes de-duplication and length filtering to optimize the final output, making it ideal for strengthening generic wordlists like [`rockyou.txt`](https://github.com/Mebus/cupp/blob/main/rockyou.txt).

### Output File Naming Convention

The enhanced wordlist saves as `<original-filename>.cupp.txt`, appending [`.cupp.txt`](https://github.com/Mebus/cupp/blob/main/.cupp.txt) to the original file name. This naming convention clearly distinguishes the mutated list from the source file, as implemented in lines 94-95 of [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py).

## Side-by-Side Comparison: Interactive vs Dictionary Improvement Mode

**Interactive Mode (`-i`)** creates a fresh wordlist from scratch by interviewing the user about a specific target. It is highly interactive, pausing for each question and validating inputs like birthdates and names. The output file uses the target's first name (e.g., [`alice.txt`](https://github.com/Mebus/cupp/blob/main/alice.txt)).

**Dictionary Improvement Mode (`-w <file>`)** augments an existing wordlist with additional variations and mutations. It requires minimal interaction, asking only a few yes/no prompts about concatenation, special characters, and leet-mode before processing. The output appends [`.cupp.txt`](https://github.com/Mebus/cupp/blob/main/.cupp.txt) to the original filename (e.g., [`rockyou.txt.cupp.txt`](https://github.com/Mebus/cupp/blob/main/rockyou.txt.cupp.txt)).

## Practical Command Examples

### Running Interactive Mode

```bash
python cupp.py -i

```

The script displays prompts such as:

```

> First Name: alice
> Surname: smith
> Nickname: al
> Birthdate (DDMMYYYY): 15081990
...

```

After answering, CUPP creates [`alice.txt`](https://github.com/Mebus/cupp/blob/main/alice.txt) containing all generated password candidates.

### Running Dictionary Improvement Mode

```bash
python cupp.py -w mywordlist.txt

```

CUPP asks minimal yes/no questions:

```

Do you want to concatenate words? [Y/n]:
Do you want to add special chars at the end of words? [Y/n]:
Do you want to add some random numbers at the end of words? [Y/n]:
Leet mode? (i.e. leet = 1337) [Y/n]:

```

The enhanced output writes to [`mywordlist.txt.cupp.txt`](https://github.com/Mebus/cupp/blob/main/mywordlist.txt.cupp.txt).

### Combined Workflow

```bash

# Step 1: Create a baseline dictionary interactively

python cupp.py -i   # Produces alice.txt

# Step 2: Improve that dictionary with extra mutations

python cupp.py -w alice.txt   # Produces alice.txt.cupp.txt

```

## Source Code Architecture

The main logic resides in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py), which contains both the `interactive()` and `improve_dictionary()` implementations. Configuration defaults for years, special characters, and number ranges are read from [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) via the `read_config()` function. Unit tests in [`test_cupp.py`](https://github.com/Mebus/cupp/blob/main/test_cupp.py) validate both modes, ensuring the combinatorial logic produces expected mutations according to the parameters defined in the configuration.

## Summary

- **Interactive mode** (`-i`) builds targeted wordlists from personal data questionnaires, ideal when you have no existing dictionary and specific target intelligence.
- **Dictionary improvement mode** (`-w`) enriches existing wordlists with mutations, concatenations, and character substitutions to increase cracking probability.
- **Output filenames** differ: interactive uses `<firstname>.txt` while improvement mode uses `<original>.cupp.txt`.
- **User interaction** varies significantly: interactive mode requires detailed personal inputs with validation, while improvement mode needs only confirmation prompts for mutation options.
- Both functions are implemented in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) with distinct entry points at lines 299-305 and 777-783 respectively.

## Frequently Asked Questions

### Can I use both interactive mode and dictionary improvement mode together?

Yes. First run `python cupp.py -i` to generate a baseline profile-specific wordlist, then process that output with `python cupp.py -w <generated_file>.txt` to apply additional mutations and expansions. This two-stage approach creates a highly targeted list then maximizes its variation potential.

### What file naming convention does CUPP use for output files?

Interactive mode names the output file after the target's first name (e.g., [`john.txt`](https://github.com/Mebus/cupp/blob/main/john.txt)), as implemented in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) lines 300-305. Dictionary improvement mode appends [`.cupp.txt`](https://github.com/Mebus/cupp/blob/main/.cupp.txt) to the original filename (e.g., [`passwords.txt.cupp.txt`](https://github.com/Mebus/cupp/blob/main/passwords.txt.cupp.txt)) according to lines 94-95 in the source code.

### Does dictionary improvement mode require an internet connection?

No. Dictionary improvement mode operates entirely offline, processing local files using the combinatorial logic defined in `improve_dictionary()`. CUPP does not require network access for either mode, though it may download updates if explicitly requested via separate update flags.

### Which mode should I use for a penetration test with no prior target information?

Use **interactive mode** (`-i`) when you have specific intelligence about the target (names, birthdates, pets). If you only have a generic wordlist like [`rockyou.txt`](https://github.com/Mebus/cupp/blob/main/rockyou.txt) and want to expand it with likely variations and mutations, use **dictionary improvement mode** (`-w`).