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

List	Original	No IP	DNSMASQ	AdGuard	Description
Abuse	Link	Link	Link	Link	Deceptive/abusive sites
Ads	Link	Link	Link	Link	Ad servers
Crypto	Link	Link	Link	Link	Cryptojacking/crypto scams
Drugs	Link	Link	Link	Link	Illegal drug sites
Facebook	Link	Link	Link	Link	Facebook/Meta services
Fraud	Link	Link	Link	Link	Fraud sites
Gambling	Link	Link	Link	Link	Gambling sites
Malware	Link	Link	Link	Link	Malware hosts
Phishing	Link	Link	Link	Link	Phishing sites
Piracy	Link	Link	Link	Link	Piracy/illegal downloads
Porn	Link	Link	Link	Link	Adult content
Ransomware	Link	Link	Link	Link	Ransomware C2/distribution
Redirect	Link	Link	Link	Link	Malicious redirects
Scam	Link	Link	Link	Link	Scam sites
TikTok	Link	Link	Link	Link	TikTok domains
Torrent	Link	Link	Link	Link	Torrent sites
Tracking	Link	Link	Link	Link	Tracking/analytics
Twitter	Link	Link	Link	Link	Twitter/X domains

Beta Lists

List	Original	No IP	DNSMASQ	AdGuard	Description
Basic	Link	Link	Link	Link	Starter protection list
Smart TV	Link	Link	Link	Link	Smart TV telemetry
Vaping	Link	Link	Link	Link	Vaping/e-cigarette sites
WhatsApp	Link	Link	Link	Link	WhatsApp domains

 

Formats

Format	Use Case	Example
Original (hosts)	Pi-hole, hosts file	0.0.0.0 example.com
No IP (domains)	Some routers, simple lists	example.com
DNSMASQ	dnsmasq DNS server	server=/example.com/
AdGuard	AdGuard Home, browser extensions	\|\|example.com^

 

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