# How to Install Holehe OSINT Tool: 3 Methods for Python-Based Email Investigation

> Easily install the Holehe OSINT tool for email investigations using PyPI, source code, or Docker. Follow our simple guide to get started with this Python-based tool.

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

---

**You can install Holehe via PyPI (`pip3 install holehe`), from source (`git clone` + `python3 setup.py install`), or using Docker, with PyPI being the recommended method for most users.**

Holehe is a lightweight, Python-based OSINT utility that checks whether an email address is registered on more than 120 online services. According to the megadose/holehe source code, the tool uses **httpx** and **trio** for async HTTP requests, dynamically loads service modules from `holehe/modules/`, and exposes both a CLI entry point in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and a programmable library interface. This guide covers all three official installation methods with exact commands and use cases for each.

## Install Holehe from PyPI (Recommended)

The fastest way to install Holehe OSINT tool is through the Python Package Index. This method requires Python 3.7+ and installs the latest stable release with all dependencies.

```bash
pip3 install holehe

```

This command pulls the package metadata defined in [[`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)](https://github.com/megadose/holehe/blob/master/setup.py), writes the `holehe` package into your site-packages directory, and registers the `holehe` console script. The entry point is implemented in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), which handles argument parsing, dynamically imports all service modules via `import_submodules()`, and orchestrates concurrent checks using `trio`.

After installation, verify it works:

```bash
holehe --help

```

## Install Holehe from GitHub Source

For developers who want to modify the code or run unreleased commits, clone the repository and run the setuptools installer.

```bash
git clone https://github.com/megadose/holehe.git
cd holehe/
python3 setup.py install

```

This method is essential if you need to:

- Edit service modules in `holehe/modules/` (e.g., [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py))
- Debug the async HTTP client initialization in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)
- Contribute patches to the dynamic module loader (`get_functions()`)

The [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) installer copies the entire source tree into your Python environment while preserving the package structure required by the module discovery system.

## Run Holehe with Docker

For isolated environments or systems without Python installed, build and run Holehe OSINT tool in a container.

```bash

# Build the image

docker build . -t my-holehe-image

# Run a check

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

```

The repository's `Dockerfile` installs all Python dependencies inside the image, including **httpx** and **trio**, so no host-side configuration is required. Add `--rm` to auto-remove the container after execution:

```bash
docker run --rm my-holehe-image holehe target@domain.com --no-color

```

## Usage Examples After Installation

### Command-Line Interface

Once you install Holehe, the CLI provides immediate email intelligence capabilities:

```bash

# Basic check across all services

holehe alice@example.com

# Show only confirmed registrations

holehe bob@example.org --only-used

# Export to CSV for reporting

holehe carol@example.net -C

```

The `--only-used` flag filters results where the `exists` field returns `True`, reducing noise in large investigations.

### Python Library Integration

Holehe can be imported as a library for custom async workflows, directly calling individual service modules:

```python
import httpx
import trio
from holehe.modules.social_media.twitter import twitter

async def main():
    email = "dave@example.com"
    results = []
    async with httpx.AsyncClient() as client:
        await twitter(email, client, results)
    print(results)
    # [{'name': 'twitter', 'domain': 'twitter.com', 'exists': True, ...}]

trio.run(main)

```

Each service module follows this pattern: an async function accepting `email`, `httpx.AsyncClient`, and a `results` list. The core CLI in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) uses the same interface, batching hundreds of these calls via trio for concurrent execution.

## Architecture Overview for Installers

Understanding these components helps troubleshoot installation issues:

| Component | Location | Purpose |
|-----------|----------|---------|
| CLI driver | [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) | Parses arguments, loads modules, runs trio event loop |
| Module loader | `import_submodules()` in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) | Discovers all service modules dynamically |
| Service implementations | `holehe/modules/*/*.py` | One file per site (120+ services) |
| Progress UI | [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) | Trio instrument for terminal progress bar |
| HTTP client | `httpx.AsyncClient` | Async requests with timeout/retry handling |

If `holehe` command fails after installation, verify that [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) registered the console script correctly and that `holehe/modules/` is importable in your Python path.

## Summary

- **PyPI install** (`pip3 install holehe`) is fastest and recommended for most users
- **Source install** enables development and customization of service modules
- **Docker install** provides complete isolation without host Python dependencies
- All methods install the same codebase: [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) for CLI, `holehe/modules/` for services, and [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) for package metadata
- Post-installation, use `holehe <email>` for immediate OSINT checks or import individual modules for programmatic use

## Frequently Asked Questions

### What Python version is required to install Holehe?

Holehe requires **Python 3.7 or newer**. The codebase uses modern async/await syntax with **trio** and **httpx**, which depend on features introduced in Python 3.7. Check your version with `python3 --version` before installing.

### Why does `holehe` command not work after pip install?

This typically occurs when pip's script directory is not in your system PATH. Run `pip3 show holehe` to locate the installation, then add the reported `Location/../bin` directory to your PATH, or use `python3 -m holehe` as an alternative entry point.

### Can I install Holehe on Windows?

Yes. All three installation methods work on Windows with Python 3.7+ installed. For Docker on Windows, use Docker Desktop with WSL2 backend. The source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) uses cross-platform path handling via `pathlib`, so no Windows-specific modifications are needed.

### How do I update Holehe to the latest version?

For PyPI installs, run `pip3 install --upgrade holehe`. For source installs, pull the latest commits with `git pull` inside the repository, then re-run `python3 setup.py install`. Docker users should rebuild the image with `docker build . -t my-holehe-image` after pulling fresh source.