Repolode
Submit
tanrax

tanrax/maza-ad-blocking

A local, OS-level ad blocker written in pure Bash that blocks ad domains for every browser and app via the hosts file or Dnsmasq.

Open-source alternative to:Pi-hole

View on GitHubWebsite
Stars
1,875
Forks
72
Open issues
2
Last commit
3 months ago

What is it?

Maza is a command-line ad blocker that runs locally on your machine instead of on a separate server like Pi-hole. It works by updating the system hosts file with a list of ad domains, so any browser or application on the computer that resolves those domains is affected, without installing browser extensions.

The tool is a single Bash script with commands to update the blocklist, start, stop and check status. It targets macOS, Linux, BSD and Windows Subsystem for Linux. For wildcard or subdomain blocking, which the hosts file cannot do, it can generate a Dnsmasq configuration and act as a local DNS server.

Users can keep a list of domains to ignore, add their own custom domains, or switch to a different source list such as Steven Black's hosts list. A cron entry can refresh the blocklist daily.

Key features

  • 01Blocks ads system-wide for any browser or application without extensions.
  • 02Runs as a single Bash script with simple start, stop, update and status commands.
  • 03Supports macOS, Linux, BSD and WSL.
  • 04Allows ignoring specific domains and adding custom blocked domains.
  • 05Can switch to alternative blocklist sources via a configuration URL.
  • 06Supports wildcard blocking through optional Dnsmasq integration.

Use cases

  • Blocking ads across all browsers and apps on a personal laptop or desktop.
  • Running a local ad blocker on Linux or macOS without installing a separate server.
  • Building a small Pi-hole-style DNS server on a Raspberry Pi or VPS with Dnsmasq.

Quick start

  1. 1

    Download the maza script and install it to /usr/local/bin

    curl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza && sudo rm -rf /usr/local/bin/maza && chmod +x maza && sudo mv maza /usr/local/bin
  2. 2

    Start blocking ads

    sudo maza start

Things to know

  • Requires sudo and edits the system hosts file, so a backup is advised.
  • The hosts file cannot block subdomains (wildcards); full filtering needs a local Dnsmasq server.
  • On macOS it also needs GNU sed (gsed) installed via Homebrew.

In collections

Open-source Mac appsPrivacy & local-first tools

Topics

#ad-blocking#bash#dns#hosts-file#dnsmasq#privacy#macos#linux#ads#blocker-proxy

FAQ

What is maza-ad-blocking?
A local, OS-level ad blocker written in pure Bash that blocks ad domains for every browser and app via the hosts file or Dnsmasq. Maza is a command-line ad blocker that runs locally on your machine instead of on a separate server like Pi-hole. It works by updating the system hosts file with a list of ad domains, so any browser or application on the computer that resolves those domains is affected, without installing browser extensions.
Is maza-ad-blocking free to use? What license does it have?
maza-ad-blocking is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is maza-ad-blocking still maintained?
Updated within 6 months. The last commit to maza-ad-blocking was on Aug 14, 2026.
What can I use maza-ad-blocking for?
Blocking ads across all browsers and apps on a personal laptop or desktop. Running a local ad blocker on Linux or macOS without installing a separate server. Building a small Pi-hole-style DNS server on a Raspberry Pi or VPS with Dnsmasq.
How do I install maza-ad-blocking?
Download the maza script and install it to /usr/local/bin: curl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza && sudo rm -rf /usr/local/bin/maza && chmod +x maza && sudo mv maza /usr/local/bin Start blocking ads: sudo maza start
Where can I get maza-ad-blocking?
The source code and installation instructions are on GitHub: https://github.com/tanrax/maza-ad-blocking

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects