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
We've completely rebuilt the project infrastructure from the ground up. After 6 months of planning, we're excited to share what's changed.
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.
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)
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.
- Copy the link for your desired list from the Available Lists section
- Go to Group Management → Adlists → Paste URL → Add
- Go to Tools → Update Gravity
- Copy the AdGuard format link for your desired list
- Go to Filters → DNS Blocklists → Add blocklist → Add a custom list
- Paste the URL and click Save
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
| 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 |
| 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 |
| Link | Link | Link | Link | Twitter/X domains |
| 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 |
| Link | Link | Link | Link | WhatsApp domains |
| 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^ |
We welcome contributions! Here's how you can help:
- Open an Add Request
- Fill out the form with the domain and evidence
- Our bot will check if it's already listed
- A maintainer will review and add it
- Open a Remove Request
- Explain why the domain should be unblocked
- A maintainer will review and remove it
- Fork the repository
- Edit the appropriate
.txtfile in the root directory - Submit a Pull Request
- Our CI will validate the changes automatically
# 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 --verbosepython 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 validationLists/
├── *.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
Special thank you to Cloud 4 SURE for their generous donation to help cover infrastructure costs.
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.
