How the `--only-used` Flag Filters Results to Show Only Confirmed Account Matches in Holehe

The --only-used flag excludes rate-limited, error, and non-existent results by checking three conditions in holehe/core.py before adding entries to the output list.

Holehe is an open-source email enumeration tool that checks whether an email address is registered on hundreds of websites. By default, it displays every result—including sites that returned errors or rate limits. The --only-used flag streamlines this output to show only confirmed account matches. This article explains exactly how this filtering works according to the megadose/holehe source code.

How Results Are Structured

Each module in Holehe returns a dictionary with standardized keys. The core processing logic in holehe/core.py evaluates these dictionaries to decide what appears in the final output.

The three key fields that control filtering are:

• results["rateLimit"] – True if the site blocked the request due to rate limiting
• results["error"] – True if the module encountered an exception or unexpected response
• results["exists"] – True if the email was found, False if not found, or None if uncertain

The Filtering Logic in holehe/core.py

The --only-used flag (args.onlyused) determines whether entries are skipped or added to the out list. The filtering occurs in three sequential checks around lines 123–132.

Excluding Rate-Limited Results

When a site responds with a rate limit, Holehe normally includes this in the output as a warning. With --only-used, these entries are excluded:

if results["rateLimit"] and args.onlyused == False:
    # Entry skipped when --only-used is enabled

This condition appears at /holehe/core.py#L123. When args.onlyused is True, this branch never executes and the rate-limited result continues to the next check.

Excluding Error Results

Modules that raise exceptions or return malformed data set results["error"] to True. These are filtered similarly:

elif "error" in results.keys() and results["error"] and args.onlyused == False:
    # Entry skipped when --only-used is enabled

Found at /holehe/core.py#L126, this check prevents error states from appearing in the filtered output.

Excluding Non-Existent Accounts

The final exclusion removes sites where the email was definitively not found:

elif results["exists"] == False and args.onlyused == False:
    # Entry skipped when --only-used is enabled

Located at /holehe/core.py#L132, this ensures only entries where results["exists"] is True or None remain for potential inclusion.

What Passes the Filter

Only entries that satisfy all of the following conditions reach the output list when --only-used is enabled:

• results["rateLimit"] is False or not present
• results["error"] is False or not present
• results["exists"] is not explicitly False (i.e., True or None)

This means confirmed matches (exists=True) and uncertain results (exists=None) are retained, while definitive negatives and failure states are discarded.

Practical Usage Examples

Default Output (All Results)

holehe user@example.com

Shows every checked site, including rate-limited services, errors, and confirmed non-matches.

Filtered Output (Confirmed Matches Only)

holehe user@example.com --only-used

Displays only services where the email address was verified or where the result remains ambiguous—hiding unsuccessful checks.

Module Implementation Details

The filtering logic depends on consistent dictionary structures from each module. For example, in holehe/modules/social_media/twitter.py and similar module files, functions return dictionaries like:

{
    "name": "twitter",
    "rateLimit": False,
    "exists": True,
    "emailrecovery": None,
    "phoneNumber": None,
    "others": None
}

The core logic at holehe/core.py consumes these structures uniformly, making the --only-used behavior consistent across all 100+ supported services.

Summary

• The --only-used flag in Holehe filters output by evaluating three conditions in holehe/core.py
• Rate-limited results are excluded via the check at line 123
• Error states are excluded via the check at line 126
• Confirmed non-matches (exists=False) are excluded via the check at line 132
• Only confirmed or uncertain matches appear in the final output

Frequently Asked Questions

Why does --only-used still show some uncertain results?

Holehe preserves entries where exists=None because these represent cases where the module could not definitively confirm or deny the account's existence. The flag only removes definitive negatives, not ambiguous states.

Can I combine --only-used with other flags?

Yes. The onlyused argument is parsed alongside other options in holehe/core.py and operates independently. You can combine it with formatting flags or timeout adjustments without conflict.

Does --only-used make Holehe run faster?

No. The flag only affects output filtering after all modules complete execution. It does not skip modules or reduce network requests—the same enumeration work occurs regardless of this setting.

Where is the argument parser defined?

The --only-used argument is added through argparse in holehe/core.py, where args.onlyused becomes a boolean that the filtering logic references at lines 123, 126, and 132.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}