# How to Run Holehe with Docker and Custom Arguments: A Complete Guide

> Learn to run Holehe with Docker and custom arguments. Build the image and pass CLI options like --no-color and --csv for efficient email checking.

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

---

**You can run Holehe in Docker by building the image once with `docker build -t holehe-image .` and then passing any CLI arguments after the image name, such as `docker run --rm holehe-image holehe test@example.com --no-color --csv`.**

The ** Holehe** open-source tool by [megadose/holehe](https://github.com/megadose/holehe) provides a lightweight Docker workflow that lets you check email address registrations across hundreds of platforms without installing Python locally. This guide shows you how to build the Docker image and use custom arguments to control output format, timeouts, and filtering.

## Building the Holehe Docker Image

The repository includes a minimal **Dockerfile** that copies the source to `/opt/holehe`, installs the package via [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py), and exposes the `holehe` console script as the entry point.

The build process is only five lines long【Dockerfile†L1-L5】:

```bash
docker build -t holehe-image .

```

This command creates a local image named `holehe-image` containing all dependencies declared in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) (including `httpx`, `trio`, and `bs4`)【setup.py†L11-L13】.

## Running Holehe with Custom Arguments

When you launch a container, any arguments placed **after the image name** are passed directly to the `holehe` command inside the container. The argument parsing logic resides in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), where `ArgumentParser` handles:

- **Positional email argument** — defined near line 81【core.py†L80-L84】
- **`--no-color`** — disables colored terminal output, added around line 86【core.py†L86-L88】
- **`--csv`** — exports results to CSV format, added around line 92【core.py†L92-L94】
- **`--timeout`** — sets request timeout in seconds
- **`--only-used`** — filters to show only platforms where the email is registered

### Basic Docker Run Syntax

```bash
docker run --rm holehe-image holehe <email> [options]

```

The `--rm` flag automatically removes the container after execution, keeping your system clean.

### Common Usage Examples

**Simple email check:**

```bash
docker run --rm holehe-image holehe alice@example.com

```

**Disable colors for CI pipelines:**

```bash
docker run --rm holehe-image holehe bob@example.org --no-color

```

**Export results to CSV:**

```bash
docker run --rm holehe-image holehe carol@test.com --csv

```

**Combine multiple options:**

```bash
docker run --rm holehe-image holehe dave@mail.net \
    --no-color --csv --timeout 15 --only-used

```

### Docker-Specific Flags vs. Holehe Arguments

Place Docker flags **before** the image name and Holehe arguments **after**:

| Position | Example | Purpose |
|----------|---------|---------|
| Before image | `-v`, `-e`, `--network` | Docker runtime configuration |
| After image | `holehe`, email, `--csv` | Passed to Holehe CLI |

For example, to mount a local directory for CSV output:

```bash
docker run --rm -v "$(pwd)/output:/output" holehe-image \
    holehe user@domain.com --csv --csvpath /output/results.csv

```

## Available Command-Line Options

Based on the implementation in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), you can customize your Docker runs with these arguments:

- **`--no-color`** — Plain text output without ANSI escape codes
- **`--csv`** — Save results to CSV file
- **`--csvpath PATH`** — Specify custom CSV output location
- **`--timeout SECONDS`** — Limit HTTP request duration (default varies by module)
- **`--only-used`** — Show only services where email is registered
- **`--no-async`** — Disable asynchronous mode

## Why Use Docker for Holehe?

Running Holehe with Docker offers several advantages:

1. **Zero Python dependencies** — No local `pip install` or virtual environment management
2. **Reproducible environment** — Consistent behavior across different machines
3. **CI/CD integration** — Easy incorporation into automated pipelines using `--no-color`
4. **Isolation** — Network requests contained within container boundaries

## Summary

- Build the image once with `docker build -t holehe-image .` using the 5-line Dockerfile【Dockerfile†L1-L5】
- Pass custom arguments after the image name; they route directly to `holehe` via the console script defined in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)
- Key arguments include `--no-color`, `--csv`, `--timeout`, and `--only-used`, parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)【core.py†L80-L94】
- Use Docker flags (`-v`, `-e`, `-p`) before the image name for runtime configuration
- The image includes all dependencies (`httpx`, `trio`, `bs4`) through [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)【setup.py†L11-L13】

## Frequently Asked Questions

### How do I pass multiple email addresses to Holehe in Docker?

Holehe accepts a single email as its positional argument. To check multiple addresses, run separate Docker commands or create a shell loop: `for email in a@b.com c@d.com; do docker run --rm holehe-image holehe "$email" --csv; done`.

### Where does the CSV output go when running Holehe with Docker?

By default, CSV files are written inside the container filesystem. Mount a host directory with `-v` and use `--csvpath` to specify an accessible location, such as `docker run --rm -v "$(pwd):/out" holehe-image holehe test@example.com --csv --csvpath /out/results.csv`.

### Can I run Holehe in Docker without building the image locally?

Yes, though megadose/holehe does not publish official images to Docker Hub. You can build from the GitHub repository directly: `docker build -t holehe-image https://github.com/megadose/holehe.git`, then run with custom arguments as described above.

### Why does my Docker run show no output or hang indefinitely?

Check your network connectivity and try increasing the timeout: `docker run --rm holehe-image holehe user@domain.com --timeout 30`. Some modules may fail silently; use `--no-color` and redirect stderr to diagnose issues: `2>&1` appended to your command.