# How to Parse Holehe Output: Complete Guide to the Python Library and CSV Export

> Easily parse Holehe output using its Python library or export to CSV. Our guide simplifies the process, helping you understand investigation results directly or via universal CSV parsing.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Holehe returns investigation results as a standardized Python dictionary list stored in the `out` variable, which you can capture directly when using the tool as a library or export to CSV via the `--csv` flag for universal parsing.**

Learning how to parse Holehe output effectively allows you to integrate this email investigation tool into automated workflows and analytics pipelines. The megadose/holehe repository structures every service check result into a predictable schema, making it straightforward to extract registration status, recovery information, and rate-limiting data programmatically or from file exports.

## Understanding the Holehe Data Structure

### The Standard Result Dictionary Schema

Each email verification produces a Python dictionary with eight standardized keys. According to the error-handling fallback in `launch_module` within [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 70-78), the schema remains consistent whether a module succeeds or fails:

- **`name`**: The internal module identifier (e.g., `instagram`)
- **`domain`**: Human-readable service domain (e.g., `instagram.com`)
- **`exists`**: Boolean indicating if the email is registered on the service
- **`rateLimit`**: Boolean flag set to `True` when the request hits rate limits
- **`error`**: Boolean flag set to `True` when the module raises an exception
- **`emailrecovery`**: Partially obfuscated recovery email address, if available
- **`phoneNumber`**: Partially obfuscated phone number associated with the account, if any
- **`others`**: Nested dictionary containing service-specific data such as `FullName` or account creation timestamps

Individual modules populate these values in files like [`holehe/modules/social_media/instagram.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/instagram.py), but the key structure remains uniform across all 120+ supported services.

## Method 1: Parse Holehe Output Programmatically (Python Library)

The most robust way to parse Holehe output is importing the tool as a Python library and capturing the `out` list directly before it reaches the display functions. The orchestration logic in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) uses `launch_module` to populate this list asynchronously.

```python
import httpx
import trio
import json
from holehe.core import import_submodules, get_functions, launch_module

async def investigate_email(email):
    # Load all service modules

    modules = import_submodules("holehe.modules")
    websites = get_functions(modules)
    
    # Initialize HTTP client and result container

    client = httpx.AsyncClient(timeout=10)
    out = []
    
    # Execute checks concurrently

    async with trio.open_nursery() as nursery:
        for site in websites:
            nursery.start_soon(launch_module, site, email, client, out)
    
    await client.aclose()
    return out  # List of dictionaries ready for parsing

# Usage example

results = trio.run(investigate_email, "target@example.com")

# Parse specific fields

for result in results:
    if result["exists"] and not result["error"]:
        print(f"{result['domain']}: Account found")
        if result["emailrecovery"]:
            print(f"  Recovery hint: {result['emailrecovery']}")

# Convert entire output to JSON for downstream processing

json_output = json.dumps(results, indent=2)

```

The `out` list contains the raw data before `print_result` (lines 6-49) formats it for terminal display or `export_csv` (lines 54-64) writes it to disk. This approach bypasses file I/O entirely and provides immediate access to the `others` dictionary for advanced data extraction.

## Method 2: Parse Holehe Output via CSV Export

For shell scripting or non-Python environments, use the CLI's built-in CSV export functionality. The `export_csv` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 54-64) generates machine-readable files with headers matching the dictionary keys exactly.

```bash
holehe target@example.com --csv

```

This creates a timestamped file following the pattern `holehe_1700000000_target@example.com_results.csv` in the current directory. Parse this file using standard CSV libraries:

```python
import csv
import glob

# Find the generated CSV file

csv_files = glob.glob("holehe_*_target@example.com_results.csv")
latest_file = max(csv_files, key=lambda x: x.split('_')[1])

# Parse into dictionaries

with open(latest_file, mode='r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    results = list(reader)

# Filter for confirmed accounts

confirmed_accounts = [
    r for r in results 
    if r["exists"] == "True" and r["error"] == "False"
]

```

The CSV columns map directly to the dictionary keys (`name`, `domain`, `exists`, `rateLimit`, `error`, `emailrecovery`, `phoneNumber`, `others`), ensuring consistent parsing across Python pandas, JavaScript PapaParse, or spreadsheet applications.

## Method 3: Parse Plain Text Output (Optional)

If you must parse the terminal output directly, suppress ANSI color codes using the `--no-color` flag to simplify regex extraction. The `print_result` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 8-12) checks `args.nocolor` to disable formatting.

```bash
holehe target@example.com --no-color --no-clear > results.txt

```

However, this method is fragile compared to the programmatic or CSV approaches, as terminal formatting changes may break parsing logic. Use this only when library installation is impossible.

## Key Files Involved in Output Generation

Understanding the source architecture helps debug parsing issues:

- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)**: Contains the `launch_module` async worker (lines 66-78) that assembles results, `print_result` (lines 6-49) for terminal formatting, and `export_csv` (lines 54-64) for file export
- **`holehe/modules/*/*.py`**: Individual service implementations that populate the result dictionaries with service-specific data in the `others` field
- **[`README.md`](https://github.com/megadose/holehe/blob/main/README.md)** (Module Output section): Documents the JSON-equivalent format specification for reference

## Summary

- **Holehe structures every result as a Python dictionary** with eight standardized keys including `exists`, `rateLimit`, and `emailrecovery`, collected into a list called `out`.
- **Import Holehe as a library** to capture the `out` list directly from `launch_module` before display processing, enabling real-time filtering and JSON serialization.
- **Use the `--csv` flag** to generate timestamped CSV files parseable by any standard library, with columns matching the internal dictionary schema exactly.
- **Reference [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** lines 66-78 for the result assembly logic and lines 54-64 for the CSV export implementation when building custom parsers.

## Frequently Asked Questions

### What is the exact schema of a Holehe result dictionary?

Each result contains the keys `name`, `domain`, `exists`, `rateLimit`, `error`, `emailrecovery`, `phoneNumber`, and `others`. The `exists` boolean indicates account registration status, while `rateLimit` and `error` signal operational issues. The `others` field holds service-specific metadata such as full names or creation dates as a nested dictionary.

### How do I export Holehe results to CSV from the command line?

Append the `--csv` flag to any Holehe command: `holehe email@example.com --csv`. The tool generates a timestamped CSV file named `holehe_[timestamp]_email@example.com_results.csv` with headers matching the internal dictionary keys. This file can be parsed by Python's `csv.DictReader`, pandas, or any spreadsheet software.

### Can I use Holehe as a Python library instead of CLI?

Yes. Import `import_submodules`, `get_functions`, and `launch_module` from `holehe.core`, then execute `launch_module` within a `trio` nursery to populate an `out` list. This list contains the raw result dictionaries before they are formatted for display, allowing direct programmatic access to all investigation data without file I/O.

### Where does Holehe assemble the final result list before display?

The `launch_module` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 66-78) appends each module's result to the `out` list passed as an argument. After all async workers complete, [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) sorts this list by the `name` key (alphabetically by service) and passes it to either `print_result` (lines 6-49) for terminal display or `export_csv` (lines 54-64) for file export.