Adlist-Parser

Fetches and merges 50+ community adlists into two normalized output files for DNS blockers like Pi-hole, AdGuard Home, and similar solutions. Updated periodically; just subscribe to the raw file URLs.

Table of Contents

• Output Files
• Using with Pi-hole
• Using with AdGuard Home
• Features
• Output Format
• FAQ
• Use Cases
• Contributing
• License
• Acknowledgments

Output Files

Subscribe to these raw URLs directly in your DNS blocker — no cloning or running anything required:

File	Raw URL	Description
Adlist	https://media.githubusercontent.com/media/Toomas633/Adlist-Parser/refs/heads/main/output/adlist.txt	~1.6M blocklist entries
Whitelist	https://media.githubusercontent.com/media/Toomas633/Adlist-Parser/refs/heads/main/output/whitelist.txt	~2K allowlist entries

Using with Pi-hole

1. Open the Pi-hole admin panel → Lists
2. Paste the adlist URL and click Add blocklist
3. Go to Tools → Update Gravity to pull the new entries

To add the allowlist:

1. On the same Lists page, paste the whitelist URL
2. Click Add allowlist
3. Go to Tools → Update Gravity to apply the allowlist

Using with AdGuard Home

1. Open AdGuard Home → Filters → DNS blocklists → Add blocklist → Add a custom list
2. Paste the adlist URL and confirm
3. For the whitelist: Filters → DNS allowlists → Add allowlist → Add a custom list, paste the whitelist URL

Features

• ~1.6M entries merged from 50+ community sources
• Dual output: blocklist and allowlist generated simultaneously
• Handles plain domains, host file format, ABP rules, Pi-hole regex, and wildcards
• Exception rules (@@||) automatically separated to the whitelist
• Deduplication and case-insensitive sorting across all sources
• Failed/unavailable sources never cause missing entries — merged with previous output

Output Format

Each output file starts with a generated header:

# Adlist - Generated by Adlist-Parser
# https://github.com/Toomas633/Adlist-Parser
#
# Created/modified: 2025-01-01 00:00:00 UTC
# Total entries: 1,684,272
# Domains: 400,527
# ABP-style rules: 1,283,745
# Sources processed: 50
#
# This file is automatically generated. Do not edit manually.
# To update, run: adlist-parser or python -m adparser
#

Entries are a mix of plain domains and ABP-style rules:

example.com
||ads.example.com^
||*.tracking.net^

Both formats are recognized by Pi-hole (via gravity) and AdGuard Home.

FAQ

Why are some entries ABP rules (||domain^) instead of plain domains? Wildcard and regex sources produce ABP-style rules, which Pi-hole and AdGuard Home both understand natively.

Why are element-hiding rules (##, #@#) missing? This tool targets DNS-level blocking. Element-hiding is browser cosmetic filtering and has no effect at the DNS layer.

Why do some regex entries disappear? Only simple, anchored Pi-hole patterns are converted to ABP. Complex regex is discarded — it is not DNS-safe.

How often are the files updated? The output files are regenerated automatically by a GitHub Actions workflow on a monthly schedule and whenever changes to the source lists (data/) are merged into main. Check the header timestamp in the raw file for the last update.

Use Cases

• Pi-hole: blocklist + allowlist
• AdGuard Home: DNS blocklist + DNS allowlist
• Any DNS-based ad blocker that accepts domain lists or ABP filter lists
• Corporate firewall domain blocking

Contributing

See DEVELOPMENT.md for architecture details, module contracts, testing, linting, VS Code tasks, and contribution conventions.

Git LFS: cache/, output/, and bulk list files in data/ are tracked via Git LFS. Run git lfs install then git lfs pull after cloning if you need those files locally.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

• Built for the DNS filtering community
• Inspired by the need for fast, reliable adlist aggregation
• Uses high-quality sources from the community (StevenBlack, Hagezi, FadeMind, and others)