# How CSV Export Works in Holehe: A Complete Technical Breakdown

> Understand Holehe CSV export functionality. Learn how Holehe generates timestamped CSV files with email investigation results using the -C flag for a complete technical breakdown.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: internals
- Published: 2026-08-25

---

**Holehe's CSV export functionality generates timestamped CSV files containing all email investigation results when the `-C` flag is passed on the command line.**

The **CSV export** capability in the Holehe OSINT tool allows security researchers and investigators to save email probe results in a structured, machine-readable format for further analysis. This feature is implemented directly in the core module and requires no external dependencies beyond Python's standard library.

## Where the CSV Export Logic Lives

The entire export pipeline resides in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). This single file handles command-line parsing, result collection, and file generation.

When you invoke Holehe with the `-C` or `--csv` flag, the `argparse` configuration in [`core.py`](https://github.com/megadose/holehe/blob/main/core.py) captures this preference and stores it in `args.csvoutput` as a boolean flag. This value determines whether the tool triggers file export after completing all site probes.

## The Export Flow: Step by Step

Holehe processes CSV export through a tightly orchestrated four-step sequence inside the `export_csv` function (line 30 in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)):

### 1. Timestamp and Filename Generation

The function first captures the current moment using `datetime.now()`, converts it to a Unix timestamp via `datetime.timestamp(now)`, and rounds it to an integer. It then constructs a deterministic filename pattern:

```

holehe_<timestamp>_<email>_results.csv

```

This naming convention ensures chronological sorting and clear association between output files and target investigations.

### 2. CSV Writer Initialization

The export routine opens the target file with specific encoding parameters:

- `encoding="utf8"` — handles international characters in domain names and recovery emails
- `newline=""` — prevents platform-specific line-ending artifacts

It instantiates `csv.DictWriter` using the keys from the first result dictionary (`data[0].keys()`) as automatic column headers. This dynamic header extraction means the CSV structure adapts to whatever fields the probe modules return.

### 3. Data Writing

The writer executes two operations:
- `writer.writeheader()` — outputs column names
- `writer.writerows(data)` — batch-writes all result dictionaries

This approach preserves the exact data structure shown in console output—including fields like `domain`, `exists`, `emailrecovery`, `phoneNumber`, and others—while transforming it into tabular format.

### 4. Completion and Exit

After file operations complete, the function flushes buffers and terminates with a status message identifying the generated file path. The program exits cleanly without returning to interactive probing.

## Practical Usage Examples

### Basic Console Output

```bash
holehe user@example.com

```

### CSV Export Mode

```bash
holehe user@example.com -C

# Output: All results have been exported to holehe_1725039200_user@example.com_results.csv

```

## Recreating the Export Logic

This minimal Python snippet mirrors Holehe's internal implementation exactly:

```python
import csv
from datetime import datetime

def export_csv(data, email):
    now = datetime.now()
    timestamp = datetime.timestamp(now)
    filename = f"holehe_{round(timestamp)}_{email}_results.csv"
    
    with open(filename, "w", encoding="utf8", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)
    
    print(f"All results have been exported to {filename}")

# Example execution

export_csv(
    [
        {"domain": "github.com", "exists": True, "emailrecovery": None},
        {"domain": "twitter.com", "exists": False, "emailrecovery": None}
    ],
    "user@example.com",
)

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) | Defines CLI parser, `export_csv` function, and post-probe export trigger |
| [`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py) | Exposes package entry point for the `holehe` command |
| `holehe/modules/*` | Site-specific check modules that populate the data structure consumed by `export_csv` |

## CSV Output Structure

The generated **CSV export** files contain one row per probed service with standardized columns. Typical fields include:

- `domain` — the service being checked
- `exists` — boolean indicating account presence
- `emailrecovery` — partial recovery email if exposed
- `phoneNumber` — partial recovery phone if exposed
- `others` — additional metadata from specific modules

Because headers derive dynamically from result dictionaries, column availability varies based on which services return data for a given email address.

## Summary

- **CSV export** activates with `-C` or `--csv` flags parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)
- The `export_csv` function generates timestamped filenames and writes UTF-8 encoded CSV
- `csv.DictWriter` uses result dictionary keys as headers for flexible schema handling
- Output files land in the working directory with predictable naming for automation pipelines
- No external dependencies required—implementation uses only Python standard library

## Frequently Asked Questions

### How do I enable CSV export in Holehe?

Pass the `-C` or `--csv` flag when invoking the tool from the command line. Holehe will automatically generate a CSV file after completing all site probes.

### Where does Holehe save the exported CSV file?

Files are saved to the current working directory with the naming pattern `holehe_<timestamp>_<email>_results.csv`. The timestamp uses Unix epoch seconds for chronological sorting.

### What columns appear in the Holehe CSV export?

Columns match the keys of the result dictionaries returned by probe modules. Common fields include `domain`, `exists`, `emailrecovery`, `phoneNumber`, and `others`, though availability varies by target service.

### Does CSV export require additional Python packages?

No. The implementation in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) uses only standard library modules: `csv`, `datetime`, and built-in file I/O. No `pip install` steps are necessary beyond the base Holehe installation.