# How to Contribute to holehe Development: A Complete Guide for Open-Source Contributors

> Learn how to contribute to holehe development. Fork the repository, add modules to holehe/modules/, and submit a pull request following the project's async check() pattern and module structure.

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

---

**Contribute to holehe by forking the repository, adding or improving modules in `holehe/modules/`, and submitting a pull request that follows the project's async `check()` pattern and module structure.**

Holehe is a Python-based open-source tool maintained by megadose that verifies whether an email address is registered across hundreds of online services. If you want to expand its coverage or improve existing functionality, this guide walks you through the exact contribution workflow based on the actual source code structure.

## Understanding the holehe Codebase Structure

Before making changes, familiarize yourself with how the project organizes its code. This knowledge prevents structural mistakes and ensures your contribution integrates seamlessly.

### Core Architecture

- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** – Contains the `Holehe` orchestration class that discovers modules and executes checks
- **`holehe/modules/`** – Category-based subdirectories holding individual service implementations
- **[`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py)** – Declares dependencies, entry points, and packaging metadata
- **[`.github/workflows/codeql-analysis.yml`](https://github.com/megadose/holehe/blob/main/.github/workflows/codeql-analysis.yml)** – CI pipeline that validates pull requests

Each service lives in a category folder such as `music/`, `programming/`, or `social/`, following the pattern established by existing modules like [`holehe/modules/music/spotify.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/music/spotify.py).

## Setting Up Your Development Environment

A proper local setup lets you test changes before submitting. Install holehe in **editable mode** so code modifications take effect immediately.

```bash

# Fork the repository on GitHub, then clone your fork

git clone https://github.com/<your-username>/holehe.git
cd holehe

# Install in editable mode with all dependencies

pip install -e .

```

Verify the installation works:

```bash
holehe -u test@example.com

```

## Adding a New Service Module

New modules follow a strict async pattern. Study [`holehe/modules/music/spotify.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/music/spotify.py) or [`holehe/modules/software/docker.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/docker.py) as reference implementations.

### Step-by-Step Module Creation

**1. Choose the correct category folder**

Place your module under the appropriate subdirectory of `holehe/modules/`. Create a new category folder if no existing one matches your service.

**2. Implement the `check()` function**

All modules expose an async function (or class method) named `check` returning a standardized dictionary:

```python

# file: holehe/modules/website/example.py

import aiohttp
from holehe.core import BaseModule

class Example(BaseModule):
    async def check(self):
        """Check if email is registered on example.com."""
        url = "https://example.com/api/users/check"
        
        async with self.session.get(url, params={"email": self.email}) as response:
            data = await response.json()
            
            return {
                "name": "example",
                "domain": "example.com",
                "method": "register",
                "frequent_rate_limit": False,
                "rateLimit": False,
                "exists": data.get("user_exists", False),
                "emailrecovery": None,
                "phoneNumber": None,
                "others": None
            }

```

**3. Use the central logger for debug output**

Import and use `holehe.logger` as demonstrated in [`holehe/modules/software/docker.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/docker.py):

```python
from holehe.core import logger

logger.debug(f"Checking {self.email} against example.com")

```

**4. Register your module**

Ensure the module is importable so `check_all()` discovers it. The project typically uses an auto-loader or explicit imports in [`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py).

## Testing Your Changes

Validate functionality before committing. Run both automated tests and manual verification.

```bash

# Run pytest if configured

pytest

# Manual verification with your specific module

python -c "
from holehe.modules.website.example import Example
import asyncio

async def test():
    ex = Example('youremail@example.com')
    result = await ex.check()
    print(result)

asyncio.run(test())
"

```

Test edge cases: rate-limited responses, invalid emails, and service downtime.

## Committing and Opening a Pull Request

Clean git history and clear communication speed up review.

### Branch Naming and Commits

```bash

# Create descriptive branch

git checkout -b add-strava-module

# Make atomic commits with clear messages

git commit -m "Add Strava fitness platform email check module"

```

### Pull Request Requirements

Include in your PR description:

- **Summary** – What service you added or what bug you fixed
- **Issue reference** – `Closes #42` if addressing a reported issue
- **Testing notes** – How you verified the module works
- **Documentation update** – Confirm you edited the **Supported services** table in [`README.md`](https://github.com/megadose/holehe/blob/main/README.md)

The maintainers will trigger the CodeQL workflow defined in [`.github/workflows/codeql-analysis.yml`](https://github.com/megadose/holehe/blob/main/.github/workflows/codeql-analysis.yml) to analyze your code for security issues and style problems.

## Improving Existing Modules

Refactoring contributions are equally valuable. Common improvement areas include:

- **Regex pattern updates** – Sites change their registration flows; update detection logic in modules like [`holehe/modules/programming/github.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/programming/github.py)
- **Rate-limit handling** – Add intelligent backoff or `frequent_rate_limit` flags
- **Error resilience** – Wrap HTTP calls in try/except blocks with proper logging

When modifying existing code, preserve the original function signature and return structure to maintain backward compatibility.

## Staying Aligned with Project Standards

Holehe has no separate [`CONTRIBUTING.md`](https://github.com/megadose/holehe/blob/main/CONTRIBUTING.md), so follow these implicit conventions visible throughout the codebase:

- **Async/await throughout** – All network operations must be non-blocking
- **Consistent return dictionaries** – Include all standard keys even if `None`
- **Minimal dependencies** – Prefer standard library and `aiohttp`; add new requirements to [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) only when essential
- **Categorized organization** – Respect the existing folder hierarchy for service types

## Summary

- Fork the megadose/holehe repository and install locally with `pip install -e .`
- Study existing modules in `holehe/modules/` to understand the async `check()` pattern
- Place new modules in appropriate category subdirectories and use `holehe.logger` for debugging
- Register modules properly so `holehe.core.Holehe` discovers them during `check_all()`
- Run tests manually and verify with `holehe -u <email>` before submitting
- Write clear commit messages and comprehensive PR descriptions referencing any related issues
- Update [`README.md`](https://github.com/megadose/holehe/blob/main/README.md) to document new supported services

## Frequently Asked Questions

### Does holehe require a formal CLA or contributor agreement?

No. The repository does not specify a Contributor License Agreement. By submitting a pull request, you agree to license your contribution under the same terms as the project's existing license. Review the repository's license file for specifics.

### What Python version should I target for holehe contributions?

The [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) file determines supported versions. Based on the codebase structure and common practice for similar tools, Python 3.7+ with async/await support is expected. Verify by checking `python_requires` in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) and test your changes against the minimum specified version.

### How do I handle services that block or rate-limit holehe checks?

Set `frequent_rate_limit: True` in your return dictionary and implement exponential backoff using `asyncio.sleep()`. Study modules with similar behavior, and ensure your code gracefully handles HTTP 429 responses without crashing the entire check sequence.

### Can I contribute documentation or translation improvements?

Yes. Documentation contributions follow the same PR workflow. Edit [`README.md`](https://github.com/megadose/holehe/blob/main/README.md) directly for user-facing changes. The project does not currently maintain separate translation infrastructure, so focus on improving the English documentation clarity or adding clarifying comments within module source files.