---

Table of Contents

• About
• Features
• Quick Start
• Available Lists
• Supported Formats
• Automation & Updates
• Contributing
• For Developers
• License

---

About

The Block List Project provides free, open-source domain blocklists for network-level content filtering. Our curated lists help you control what gets blocked on your network — from ads and trackers to malware and adult content.

Why Block List Project?

• 🎯 Granular Control — Choose specific categories instead of all-or-nothing blocking
• 🔄 Always Updated — Automated builds, upstream monitoring, and community contributions
• 🔧 Format Flexibility — Pi-hole, AdGuard Home, dnsmasq, hosts files, and more
• ✅ Battle-Tested — Validated with 151+ automated tests on every change
• 🤝 Community-Driven — Submit additions/removals via GitHub Issues
• 💯 Truly Free — No premium tiers, no paywalls, no restrictions

---

---

Features

🤖 Automated Maintenance

• Upstream Source Monitoring — Automatically sync with trusted upstream blocklists
• Dead Domain Detection — Weekly scans remove defunct domains
• Issue Triage Bot — Automatically validates submissions and checks duplicates
• DNS/HTTP Validation — Verifies domains before adding them

🛡️ Quality Assurance

• TLD Verification — Ensures valid top-level domains
• Duplicate Detection — Prevents redundant entries across lists
• Critical Domain Protection — Safeguards against blocking essential services
• Format Sync — All formats generated from single source

📊 Comprehensive Coverage

• 18 Main Lists — Ads, malware, phishing, tracking, gambling, and more
• 4 Beta Lists — Basic protection, Smart TV, vaping, WhatsApp
• Multiple Formats — hosts, domain-only, dnsmasq, AdGuard
• Regular Updates — New domains added daily from community and upstream sources

---

Quick Start

Pi-hole Setup

1. Navigate to Group Management → Adlists
2. Paste a list URL from the Available Lists section
3. Click Add, then go to Tools → Update Gravity

AdGuard Home Setup

1. Go to Filters → DNS Blocklists → Add blocklist
2. Select Add a custom list
3. Paste an AdGuard format URL and click Save

Other DNS Solutions

Choose the appropriate format for your software:

Software	Format to Use	Example
Hosts file	Original	0.0.0.0 example.com
Unbound, pfBlockerNG	No IP (domains)	example.com
dnsmasq	DNSMASQ	server=/example.com/
AdGuard, uBlock Origin	AdGuard	`

---

Available Lists

Main Lists

List	Original/Pi-Hole Native	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

📌 Note about the "Everything" List
The combined "everything" list (which merged all stable lists) has been removed as of July 2026 due to exceeding GitHub's 100MB file size limit. The files grew too large for the repository:

• everything.txt: 125 MB
• everything-ags.txt: 102 MB
• everything-nl.txt: 125 MB
• everything-dnsmasq.txt: 130 MB

Alternative: To achieve similar coverage, subscribe to multiple individual lists in your DNS solution. Most tools support multiple blocklist subscriptions and will automatically merge them.

---

Supported Formats

All lists are available in four formats, automatically generated from a single source:

Format	Use Case	Syntax	File Extension
Original (hosts)	Pi-hole, hosts file, RPZ	0.0.0.0 example.com	.txt
No IP (domains)	Unbound, routers, simple lists	example.com	-nl.txt
DNSMASQ	dnsmasq DNS server	server=/example.com/	-dnsmasq.txt
AdGuard	AdGuard Home, browser extensions	`

---

Automation & Updates

Upstream Source Monitoring

The project automatically syncs with 14 trusted upstream blocklists across 8 categories:

• Daily Monitoring — GitHub Actions checks for updates at 2 AM UTC
• Auto-PR Creation — New domains trigger pull requests with size-based labels
• Smart Merging — Small updates (≤10 domains) are auto-merge candidates
• Exclusion Support — Removed domains stay removed, even if upstream re-adds them

Current Sources: ShadowWhisperer, zachlagden, Hagezi, and more.

See UPSTREAM_MONITORING.md for configuration details.

Automated Maintenance

• Dead Domain Removal — Weekly scans identify and remove inactive domains
• Issue Triage — Bot automatically validates submissions, checks for duplicates
• Stale Issue Cleanup — Inactive issues auto-close after 60 days (PRs after 90 days)
• Weekly Reports — Automated statistics and activity summaries

CI/CD Pipeline

Every change triggers:

• ✅ 151 automated tests
• ✅ Domain syntax validation
• ✅ TLD verification
• ✅ Duplicate detection
• ✅ Format regeneration for all outputs
• ✅ Code quality checks (Ruff, MyPy)

---

Contributing

We welcome and encourage community contributions! There are several ways to help:

🎯 Request Domain Changes

Add a malicious domain:

• Open an Add Request
• Provide the domain and evidence (why it should be blocked)
• Our triage bot will check if it's already listed

Remove a false positive:

• Open a Remove Request
• Explain why the domain is incorrectly blocked
• Maintainers will review and process the removal

💻 Direct Code Contributions

Important: Only edit source .txt files in the root directory. Files in adguard/, alt-version/, and dnsmasq-version/ are auto-generated — never edit these directly.

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Lists.git
cd Lists

# 2. Install dev dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

# 3. Create feature branch
git checkout -b add-malicious-domain

# 4. Edit the source file
echo "0.0.0.0 badads.example.com" >> ads.txt

# 5. Test and validate
pytest
python build.py --validate

# 6. Commit and push
git add ads.txt
git commit -m "Add badads.example.com to ads list"
git push origin add-malicious-domain

# 7. Open Pull Request on GitHub

Our CI automatically validates PRs with:

• ✅ Domain syntax checking
• ✅ Duplicate detection
• ✅ TLD verification
• ✅ All 151 test suite
• ✅ Code quality checks

See CONTRIBUTING.md for detailed guidelines.

---

For Developers

Quick Setup

# Clone and setup
git clone https://github.com/blocklistproject/Lists.git
cd Lists
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

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

# Setup pre-commit hooks
pre-commit install

# Verify installation
pytest

Building Lists

# Build all lists
python build.py

# Build specific list(s)
python build.py --list ads
python build.py --list ads --list malware --list phishing

# Validate without building
python build.py --dry-run --validate

# Build with verbose output
python build.py --verbose

Code Quality

We use modern Python tooling for code quality:

# Run tests with coverage
pytest -v --cov=src --cov-report=html

# Lint and format (Ruff - 10-100x faster than flake8/black)
ruff check .           # Check for issues
ruff check . --fix     # Auto-fix issues
ruff format .          # Format code

# Type checking
mypy src/

# Run all pre-commit hooks
pre-commit run --all-files

Pre-commit hooks automatically run on every commit:

• Ruff linting and formatting
• YAML/JSON/TOML validation
• Trailing whitespace removal
• MyPy type checking
• Private key detection

Environment Variables

Optional configuration for custom deployments:

# Project paths (defaults to current directory)
export PROJECT_ROOT=/path/to/Lists
export WORKSPACE_DIR=/path/to/Lists

# Temporary files location (defaults to /tmp)
export TEMP_DIR=/custom/tmp

# GitHub API access (for scripts that fetch issues)
export GITHUB_TOKEN=your_github_token_here

Project Structure

Lists/
├── *.txt                      # Source blocklists (hosts format) - EDIT THESE
├── *.ip                       # IP-based blocklists
├── adguard/                   # AdGuard format (auto-generated)
├── alt-version/               # Domain-only format (auto-generated)
├── dnsmasq-version/           # dnsmasq format (auto-generated)
├── build.py                   # CLI build tool
├── pyproject.toml             # Project configuration
├── requirements.txt           # Python dependencies
├── .pre-commit-config.yaml    # Pre-commit hooks
│
├── config/
│   └── lists.yml              # List definitions and upstream sources
│
├── src/                       # Python package
│   ├── config.py              # Configuration and path management
│   ├── logger.py              # Structured logging
│   ├── exceptions.py          # Custom exception types
│   ├── domain_lookup.py       # Unified domain search
│   ├── normalize.py           # Format parsing and normalization
│   ├── merge.py               # Deduplication logic
│   ├── validate.py            # Domain validation and TLD checking
│   ├── format.py              # Output format generators
│   └── pipeline.py            # Build orchestration
│
├── scripts/                   # Utility scripts
│   ├── monitor_upstream.py    # Upstream source monitoring
│   ├── remove_domain.py       # Domain removal automation
│   ├── review_issues_batch.py # Issue triage automation
│   ├── fetch_issues.py        # GitHub issue fetching
│   ├── process_maintenance.py # Dead domain checking
│   └── ...                    # Additional utilities
│
├── tests/                     # Test suite (151+ tests)
│   ├── test_config.py
│   ├── test_normalize.py
│   ├── test_validate.py
│   ├── test_merge.py
│   ├── test_format.py
│   └── test_pipeline.py
│
└── .github/workflows/         # CI/CD automation
    ├── build.yml              # Build and test pipeline
    ├── upstream-monitor.yml   # Upstream source monitoring
    ├── triage.yml             # Automatic issue triage
    ├── scheduled-triage.yml   # Daily issue processing
    ├── stale.yml              # Stale issue cleanup
    ├── weekly-report.yml      # Weekly statistics
    └── dead-domains.yml       # Dead domain detection

Key Modules

Module	Purpose
src/config.py	Environment-aware configuration, YAML loading, path management
src/validate.py	Domain syntax validation, TLD verification, critical domain protection
src/pipeline.py	Build orchestration, coordinates all build steps
src/domain_lookup.py	Unified domain search across all list formats
src/logger.py	Structured logging with console and file output
src/exceptions.py	Custom exception hierarchy (ConfigurationError, ValidationError, etc.)

Utility Scripts

Located in scripts/ directory:

Script	Description
monitor_upstream.py	Monitor upstream sources and create PRs for updates
remove_domain.py	Automated domain removal with exclusion support
review_issues_batch.py	Automated issue triage and batch processing
fetch_issues.py	Fetch and cache GitHub issues
process_maintenance.py	Scan for and remove dead domains

Run with: python scripts/<script-name>.py

Troubleshooting

Import errors:

pip install -e ".[dev]" --force-reinstall

Pre-commit hooks not working:

pre-commit clean
pre-commit install
pre-commit autoupdate

Test failures:

pytest tests/test_validate.py -v      # Run specific test
pytest -vv --tb=long                  # Verbose with full tracebacks
pytest --lf                           # Re-run last failed tests

Build errors:

python build.py --validate --verbose  # Validate with detailed output
python build.py --list <name> --verbose  # Build specific list with logging

---

What's New

v2.0 Complete Rewrite (2026)

We rebuilt the entire project infrastructure from the ground up:

For Users:

• ✅ All existing URLs continue to work
• ✅ Same lists, formats, and locations
• ✅ Improved accuracy and quality

For Contributors:

• ✅ Structured issue templates
• ✅ Automated triage bot
• ✅ Pre-commit hooks
• ✅ Modern Python tooling (Ruff, MyPy)

Technical Improvements:

• Replaced 7 JavaScript scripts with unified Python codebase
• Added 151 automated tests
• Config-driven architecture
• Proper domain validation and TLD verification
• Critical domain protection
• Upstream source monitoring
• Dead domain detection
• Structured logging and error handling

See docs/Optimize.md for the full technical deep dive.

---

Sponsors & Support

Special thanks to Cloud 4 SURE for helping cover infrastructure costs.

Support the project:

• ☕ Ko-fi
• 🎨 Patreon
• ⭐ Star this repository
• 🐛 Report issues and suggest improvements
• 💬 Join our Discord community

---

License

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

_{These files are provided "AS IS", without warranty of any kind, express or implied. In no event shall the authors or copyright holders be liable for any claim, damages or other liability arising from the use of these files.}

_{All trademarks are the property of their respective owners.}