GitHub - blocklistproject/Lists: Primary Block Lists

The Block List Project

Table of Contents

• About
• What's New in v2.0
• Quick Start
• Available Lists
• Formats
• Contributing
• For Developers
• License

About

The Block List Project provides curated domain blocklists for various categories of unwanted content. Our lists are designed to give you control over what gets blocked, rather than an all-or-nothing approach.

All lists are:

• ✅ Free and open source — always will be
• ✅ Regularly updated — automated builds on every change
• ✅ Available in multiple formats — Pi-hole, AdGuard, dnsmasq, and more
• ✅ Community maintained — submit requests via GitHub Issues

What's New in v2.0

We've completely rebuilt the project infrastructure from the ground up. After 6 months of planning, we're excited to share what's changed.

Why We Rewrote Everything

The old system worked, but it was held together with duct tape. We had a mix of JavaScript and Python scripts that nobody wanted to touch, inconsistent build processes, and no automated testing. When bugs appeared, fixing one thing broke another.

We needed something maintainable — not just for us, but for anyone who wants to contribute.

What Changed

For Users: Nothing breaks! All your existing URLs continue to work. Same lists, same formats, same locations. We rebuilt the engine without changing the car.

For Contributors:

• New structured issue templates make it easier to request additions or removals
• Our triage bot automatically checks if a domain already exists in our lists
• Pull requests now get validated automatically — no more waiting for a human to catch simple errors

Under the Hood:

• Replaced 7 JavaScript scripts with a single Python codebase
• Added 151 automated tests (yes, really)
• Config-driven architecture — all list definitions live in config/lists.yml
• Proper domain validation catches invalid entries before they ship
• TLD verification ensures we don't accidentally block legitimate domains
• Critical domain protection prevents catastrophic mistakes (no more accidentally blocking google.com)

The Technical Bits

If you're curious about the architecture:

Old System:              New System:
─────────────            ─────────────
7 JS scripts             1 Python package
0 tests                  151 tests
Manual validation        Automated validation
Ad-hoc builds            CI/CD pipeline
Mixed formats            Config-driven formats

The new build system runs pytest on every change, validates domain syntax, checks TLDs against the public suffix list, and generates all four output formats automatically. Everything flows through a single build.py CLI.

We wrote about the full rationale in our archived optimization document if you want the deep dive.

Quick Start

Pi-hole

1. Copy the link for your desired list from the Available Lists section
2. Go to Group Management → Adlists → Paste URL → Add
3. Go to Tools → Update Gravity

AdGuard Home

1. Copy the AdGuard format link for your desired list
2. Go to Filters → DNS Blocklists → Add blocklist → Add a custom list
3. Paste the URL and click Save

Other DNS Blockers

Use the appropriate format for your software:

• Hosts file format: Use the "Original" links
• Domain-only format: Use the "No IP" links
• dnsmasq: Use the "DNSMASQ" links
• AdGuard/AdBlock: Use the "AdGuard" links

Available Lists

Main Lists

Beta Lists

Formats

Contributing

We welcome contributions! Here's how you can help:

Request a Domain Addition

1. Open an Add Request
2. Fill out the form with the domain and evidence
3. Our bot will check if it's already listed
4. A maintainer will review and add it

Report a False Positive

1. Open a Remove Request
2. Explain why the domain should be unblocked
3. A maintainer will review and remove it

Direct Contributions

1. Fork the repository
2. Edit the appropriate .txt file in the root directory
3. Submit a Pull Request
4. Our CI will validate the changes automatically

For Developers

Building Locally

# Clone the repository
git clone https://github.com/blocklistproject/Lists.git
cd Lists

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Build all lists
python build.py

# Build specific list
python build.py --list ads

# Dry run (preview without writing)
python build.py --dry-run --verbose

CLI Commands

python build.py --help          # Show all options
python build.py list            # List available blocklists
python build.py stats           # Show domain counts
python build.py verify          # Verify output consistency
python build.py --validate      # Build with validation

Project Structure

Lists/
├── *.txt                 # Source blocklists (hosts format)
├── adguard/              # AdGuard format output
├── alt-version/          # Domain-only format output
├── dnsmasq-version/      # dnsmasq format output
├── config/
│   └── lists.yml         # List definitions and settings
├── src/                  # Python source code
│   ├── config.py         # Configuration loader
│   ├── normalize.py      # Format parsing
│   ├── merge.py          # Deduplication
│   ├── validate.py       # Domain validation
│   ├── format.py         # Output formatters
│   └── pipeline.py       # Build orchestration
├── tests/                # Test suite
└── build.py              # CLI entry point

Sponsors

Special thank you to Cloud 4 SURE for their generous donation to help cover infrastructure costs.

License

This project is licensed under the Unlicense — free and open source, no restrictions.

^{These files are provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, arising from, out of or in connection with the files or the use of the files.}

_{Any and all trademarks are the property of their respective owners.}