# How to Run Holehe Using Docker and Set Environment Variables

> Learn to run Holehe with Docker. Build the image, pass email as an argument, and use environment variables for custom configurations. Persist output with volume mounts.

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

---

**Run Holehe in Docker by building the included Dockerfile, then pass your target email as a command argument; use `-e` flags for optional environment variables and volume mounts to persist output.**

Holehe is an **email reconnaissance tool** that checks whether an address is registered across hundreds of online services. The megadose/holehe repository provides a ready-to-use Dockerfile that packages the Python tool with all dependencies. This guide explains how to build the image, configure runtime behavior, and handle environment considerations based on the actual source code structure.

## Building the Docker Image

The Dockerfile at the repository root uses a multi-stage approach to create a minimal, secure image.

Key characteristics from `Dockerfile`:

- **Base image**: `python:3-slim` for a small footprint with `pip` available
- **Dependency resolution**: Copies and installs [`requirements.txt`](https://github.com/megadose/holehe/blob/main/requirements.txt) before source code, leveraging Docker layer caching
- **Source installation**: Copies the entire `holehe/` package directory, preserving the internal module structure (e.g., `holehe/modules/software/`, `holehe/modules/shopping/`)
- **Non-root execution**: Creates and runs as UID 1000 to reduce attack surface
- **Entry point**: Uses the `holehe` console script defined in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)

Build the image with a local tag:

```bash
docker build -t holehe .

```

## Running Holehe in Docker

### Basic Usage

After building, invoke the tool by passing the target email as an argument:

```bash
docker run --rm holehe user@example.com

```

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

### Using Environment Variables

While Holehe primarily accepts arguments via command line, you can inject values through environment variables for scripting convenience:

```bash

# Export email to environment and reference in container

export TARGET_EMAIL="user@example.com"
docker run --rm -e TARGET_EMAIL="$TARGET_EMAIL" holehe "$TARGET_EMAIL"

```

For automated workflows, combine with shell variable expansion:

```bash
docker run --rm -e EMAIL="$1" holehe "$EMAIL"

```

### Persisting Output

By default, Holehe prints results to STDOUT. Capture output by redirecting to a mounted volume:

```bash
mkdir -p ./results
docker run --rm -v "$(pwd)/results:/out" holehe user@example.com > ./results/report.txt

```

Or use a bind mount with explicit output redirection inside the container:

```bash
docker run --rm -v "$(pwd)/reports:/data" holehe user@example.com | tee ./reports/output.json

```

## Required and Optional Environment Considerations

### Network Configuration

Holehe requires **outbound internet access** to query service APIs and websites. Verify your Docker network allows HTTPS traffic:

```bash

# Test with default bridge network

docker run --rm --network bridge holehe test@example.com

```

**Corporate proxies**: If running behind a proxy, pass environment variables:

```bash
docker run --rm \
  -e HTTP_PROXY="http://proxy.company.com:8080" \
  -e HTTPS_PROXY="http://proxy.company.com:8080" \
  holehe user@example.com

```

### Rate Limiting and Concurrency

Many services implement IP-based rate limiting. The [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) CLI accepts a `--threads` parameter to control concurrent requests:

```bash

# Limit to 5 concurrent threads to reduce rate limit triggers

docker run --rm holehe --threads 5 user@example.com

```

Avoid running multiple container instances simultaneously from the same IP, as this aggregates request counts and increases ban risk.

### Resource Constraints

Holehe is CPU-light but may open many concurrent connections. Constrain resources for production deployments:

```bash
docker run --rm \
  --cpus="1.0" \
  --memory="512m" \
  --memory-swap="512m" \
  holehe user@example.com

```

### Security Hardening

The Dockerfile implements several security practices worth preserving:

| Practice | Implementation |
|----------|---------------|
| Non-root execution | `USER 1000` directive in Dockerfile |
| Minimal base image | `python:3-slim` instead of full Debian |
| No secrets in image | Runtime-only environment variables |
| Read-only layers | Source code copied before runtime |

Do **not** rebuild with hardcoded credentials or email addresses, as these become visible in image history via `docker history`.

## Key Source Files Reference

Understanding these files helps troubleshoot Docker issues:

- **`Dockerfile`** — Defines build stages, dependency installation, and runtime configuration
- **[`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)** — Declares package metadata and the `holehe` console script entry point
- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** — Implements CLI argument parsing and orchestrates module execution
- **`holehe/modules/`** — Service-specific check implementations organized by category (programming, shopping, social, etc.)

## Complete Workflow Example

```bash

# 1. Clone and enter repository

git clone https://github.com/megadose/holehe.git
cd holehe

# 2. Build image

docker build -t holehe:latest .

# 3. Create output directory

mkdir -p ./holehe-results

# 4. Run with resource limits and output capture

docker run --rm \
  --cpus="0.5" \
  --memory="256m" \
  -v "$(pwd)/holehe-results:/output" \
  -e TZ=UTC \
  holehe:latest \
  target@example.com \
  --threads 3 \
  > ./holehe-results/run.log 2>&1

```

## Summary

- **Build once**: Use `docker build -t holehe .` from the repository root to create the image
- **Run simply**: Pass email addresses as positional arguments; output defaults to STDOUT
- **Configure via environment**: Use `-e` flags for proxy settings, timezone, or wrapper scripts
- **Persist with volumes**: Mount host directories to capture results across container restarts
- **Control concurrency**: Use `--threads` to manage rate limits and resource usage
- **Secure by default**: The image runs non-root with minimal dependencies; keep secrets out of build context

These patterns align with the Dockerfile's design as an ephemeral, reproducible execution environment for the Holehe reconnaissance tool.

## Frequently Asked Questions

### Does Holehe require any mandatory environment variables?

No mandatory environment variables exist. The tool operates entirely through command-line arguments. Optional variables like `HTTP_PROXY`, `HTTPS_PROXY`, or custom variables for wrapper scripts can be passed with `-e` flags but are not required for basic functionality.

### How do I handle rate limits when running multiple Docker containers?

Reduce `--threads` per container and stagger execution times. Running containers sequentially or from different IP addresses prevents service-side blocking. The source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) processes modules concurrently, so thread count directly impacts request velocity.

### Can I run Holehe without building the Docker image myself?

The megadose/holehe repository distributes a Dockerfile but not pre-built images on Docker Hub. You must build locally from the Dockerfile or use a CI/CD pipeline to publish internally. The build process completes in under two minutes on standard hardware.

### Where are the service-specific check modules located in the container?

Inside the container, modules reside at `/app/holehe/modules/` (or equivalent path based on `WORKDIR` in Dockerfile), with subdirectories like `programming/`, `shopping/`, `social/` matching the repository structure. These are copied during the `COPY holehe/ /app/holehe/` build step.