How to Run Holehe Using Docker and Set Environment Variables

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 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

Build the image with a local tag:

docker build -t holehe .

Running Holehe in Docker

Basic Usage

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

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:

# 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:

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:

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:

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:

# Test with default bridge network

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

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

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 CLI accepts a --threads parameter to control concurrent requests:

# 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:

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 — Declares package metadata and the holehe console script entry point
• 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

# 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 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.

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