Lists

Primary Block Lists

View the Project on GitHub blocklistproject/Lists

Block List Project Logo # The Block List Project **Curated, community-maintained domain blocklists for network-level content filtering** [![Build](https://github.com/blocklistproject/Lists/workflows/Build%20Blocklists/badge.svg)](https://github.com/blocklistproject/Lists/actions) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![License](https://img.shields.io/github/license/blocklistproject/lists?color=blue)](LICENSE) [![GitHub Issues](https://img.shields.io/github/issues/blocklistproject/lists)](https://github.com/blocklistproject/Lists/issues) [![Contributors](https://img.shields.io/github/contributors/blocklistproject/lists)](https://github.com/blocklistproject/Lists/graphs/contributors) [Discord](https://discord.com/invite/x9KeVQggkc) • [Patreon](https://www.patreon.com/bePatron?u=8892646) • [Ko-fi](https://ko-fi.com/P5P521OPP) • [Documentation](docs/)

Table of Contents

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?

Alt

Features

🤖 Automated Maintenance

🛡️ Quality Assurance

📊 Comprehensive Coverage

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 ||example.com^

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 ||example.com^ -ags.txt

Automation & Updates

Upstream Source Monitoring

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

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

See UPSTREAM_MONITORING.md for configuration details.

Automated Maintenance

CI/CD Pipeline

Every change triggers:

Contributing

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

🎯 Request Domain Changes

Add a malicious domain:

Remove a false positive:

💻 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:

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:

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:

For Contributors:

Technical Improvements:

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:

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.