# How to Run Holehe Using Docker: Complete Installation and Usage Guide

> Learn to run Holehe using Docker for isolated OSINT checks. Build the image and execute the container easily. Get the complete installation and usage guide now.

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

---

**To run Holehe using Docker, build the image from the repository's Dockerfile and execute the container with your target email address to perform isolated OSINT checks without installing Python dependencies on your host system.**

Holehe is an open-source email OSINT tool developed by megadose/holehe that checks if an email address is registered across various online platforms. Running Holehe using Docker provides a clean, isolated environment that eliminates Python version conflicts and dependency issues on your local machine. The official Dockerfile creates a lightweight container based on Python 3.11-slim, making it ideal for security researchers and automated CI pipelines.

## How the Holehe Docker Image Works

The containerization strategy for Holehe follows a straightforward build pattern defined in the repository root's `Dockerfile`. The image uses the official `python:3.11-slim` base—based on Debian Bullseye—to minimize the attack surface while maintaining compatibility with all required libraries.

### Dockerfile Structure and Installation Process

Inside `Dockerfile`, the build process copies the entire repository into `/opt/holehe` and sets this as the working directory. The image then executes `python3 setup.py install` to register the **holehe** console script entry point defined in [`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py). This installation step ensures the `holehe` command is available system-wide within the container, while [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) contains the orchestration logic executed when you run the tool.

## Building the Holehe Docker Image

Before running Holehe using Docker, you must build the image from the source code. This one-time process installs all dependencies declared in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) and prepares the runtime environment.

```bash

# Clone the repository (if not already downloaded)

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

# Build the Docker image

docker build . -t holehe-image

```

The `docker build` command reads the Dockerfile, copies the source to `/opt/holehe`, and executes the setup installation. Once complete, your local Docker daemon contains a tagged image named `holehe-image` ready for execution.

## Executing Holehe in a Docker Container

With the image built, you can run Holehe using Docker by passing your target email address as an argument to the container. The execution creates a temporary, isolated instance that automatically cleans up after completion.

```bash

# Run Holehe against a target email

docker run --rm holehe-image holehe test@example.com

```

In this command:

- `--rm` removes the container after execution, preventing accumulation of stopped containers
- `holehe-image` specifies the built image name
- The final `holehe test@example.com` invokes the CLI entry point installed during the build process

The container executes the core logic from [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) inside the isolated environment, returning results to your terminal without modifying your host system.

## Benefits of Containerized OSINT

Running Holehe using Docker offers specific advantages for security workflows:

- **Dependency isolation**: The image bundles all requirements from [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py), preventing conflicts with host Python packages
- **Minimal footprint**: The Python 3.11-slim base keeps the image size small for quick CI/CD integrations
- **Reproducible environments**: Every container runs identical code copied from the repository root during the build phase
- **Security boundary**: The Debian Bullseye-based container provides process isolation when investigating potentially sensitive email addresses

## Summary

- The `Dockerfile` in megadose/holehe uses `python:3.11-slim` as its base image and installs the tool via `python3 setup.py install`
- Build the image locally using `docker build . -t holehe-image`
- Execute OSINT checks with `docker run --rm holehe-image holehe <email>`
- The container places Holehe in `/opt/holehe` and registers the `holehe` entry point used by the CLI
- Docker execution eliminates host-side Python dependency management and version conflicts

## Frequently Asked Questions

### Do I need Python installed on my host machine to run Holehe using Docker?

No. The Docker image contains a complete Python 3.11 runtime and all dependencies specified in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py). You only need the Docker engine installed on your host system to build and run the container.

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

You can pass multiple emails as separate arguments at the end of the `docker run` command. The container executes the `holehe` CLI with whatever arguments you provide after the image name, processing each email sequentially through the logic defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).

### Where is the Holehe source code located inside the Docker container?

The Dockerfile copies the entire repository to `/opt/holehe` during the build process and sets this as the working directory. This location contains [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py), the `holehe/` package directory, and all module files including [`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py) and [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).

### Can I customize the Docker image to include additional tools or configurations?

Yes. Since the image builds from the standard `Dockerfile` in the repository root, you can modify the build instructions to install additional packages, change the working directory from `/opt/holehe`, or adjust the Python version, though the official image targets Python 3.11 for compatibility.