# How to Add Custom Special Characters for Password Generation in CUPP

> Easily add custom special characters to CUPP password generation. Edit cupp.cfg and confirm the prompt in interactive mode for enhanced security.

- Repository: [Mebus/cupp](https://github.com/Mebus/cupp)
- Tags: how-to-guide
- Published: 2026-07-01

---

**Adding custom special characters to CUPP requires editing the `chars=` line in the `[specialchars]` section of [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) with comma-separated symbols, then running CUPP in interactive mode and confirming the special characters prompt.**

CUPP (Common User Passwords Profiler) generates targeted wordlists by combining personal information with configurable special characters. The tool stores its symbol set in an external configuration file, allowing security researchers to customize password generation without modifying the Python source code.

## Understanding CUPP's Special Character System

### Configuration Loading

According to the Mebus/cupp source code, the `read_config()` function in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) (lines 66-67) parses [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) at startup and stores the special characters list in `CONFIG["global"]["chars"]`. This dictionary drives all subsequent password generation operations.

### Generation Logic

When you run CUPP in interactive mode (`-i`) or improve mode (`-w`), the script prompts *"Do you want to add special chars at the end of words?"* (lines 250-255). If you confirm, the code iterates through the configured character set up to three levels deep (lines 260-268), appending each combination to candidate passwords. This nested loop structure automatically incorporates any symbols you define in the configuration file.

## Step-by-Step Guide to Adding Custom Characters

1. **Locate the configuration file.** Open [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) in the repository root directory. This file contains all runtime parameters for the wordlist generator.

2. **Find the special characters section.** Navigate to the `[specialchars]` stanza, typically found around lines 29-34 in [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg).

3. **Modify the character list.** Edit the `chars=` line to include your desired symbols as comma-separated values. For example:

   ```ini
   [specialchars]
   chars=!,@,#,$,%,^,&,*,?,~,+,=
   ```

4. **Save the file.** No changes to [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) are required because the configuration loads dynamically at runtime.

## Running CUPP with Custom Characters

After updating the configuration, execute CUPP in interactive mode:

```bash
python3 cupp.py -i

```

When prompted *"Do you want to add special chars at the end of words?"*, answer **Y**. The generator will now append your custom symbols to all password candidates. The output file (typically named after the target, such as [`john.txt`](https://github.com/Mebus/cupp/blob/main/john.txt)) will contain entries like:

```

john!john1
john@123
john~2020
john!=2024

```

## Extending Combination Depth (Optional)

By default, CUPP generates combinations up to three special characters deep via nested loops in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) (lines 260-268). If your use case requires longer sequences (such as four or five trailing symbols), you must manually extend these loops in the source code. For most penetration testing scenarios, the default three-character depth provides sufficient coverage.

## Summary

- **Configuration location:** Edit [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) in the repository root, specifically the `[specialchars]` section.
- **No code changes required:** [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) reads `CONFIG["global"]["chars"]` dynamically via `read_config()`.
- **Format:** Use comma-separated values in the `chars=` line.
- **Activation:** Run with `-i` or `-w` flags and confirm the special characters prompt.
- **Output:** Generated wordlists automatically include passwords ending with your custom symbols.

## Frequently Asked Questions

### Where does CUPP store its special characters configuration?

CUPP stores special characters in the [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) file at the repository root, within the `[specialchars]` section. The `read_config()` function in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) loads these values into `CONFIG["global"]["chars"]` during startup.

### Can I add special characters without modifying Python code?

Yes. You only need to edit the [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) file. Add your symbols to the `chars=` line as comma-separated values, save the file, and run CUPP normally. The tool reads the configuration dynamically, so no changes to [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py) are necessary.

### Is there a limit to how many special characters I can add?

There is no hardcoded limit in the configuration parser. You can add as many comma-separated symbols as needed. However, remember that each additional character increases the wordlist size exponentially due to the three-level combination generation in lines 260-268 of [`cupp.py`](https://github.com/Mebus/cupp/blob/main/cupp.py).

### Does CUPP support multi-character strings as special characters?

The configuration parser splits the `chars=` value by commas, so individual entries can technically contain multiple characters (like `abc` or `?!`). However, the generation logic treats each entry as a single unit to append, so test your specific use case to ensure the output matches your expectations.