wBlock for Safari: A Free GPL-3.0 Content Blocker with Userscripts and Userstyles

What wBlock Solves, and Who It Is Actually For

Safari's content blocking API is not the same as the extension APIs Chrome and Firefox expose. Rules are compiled ahead of time, handed to the browser, and evaluated out of process. That design keeps memory low but caps how many rules a single extension can carry, which is why most Safari blockers ship a handful of lists and stop there. wBlock's answer is to spread 750,000 rules across five Safari content blocking extensions per platform, at 150,000 each, and to distribute rules automatically across those slots. The README describes this as maximum coverage.

The audience is narrow and specific. If you use Safari on a Mac, an iPhone, an iPad or an Apple Vision Pro and you want the kind of control uBlock Origin users take for granted, wBlock is one of the few projects in that space that is both free and GPL-3.0. It also supports userscripts with a Greasemonkey API subset (GM_getValue, GM_setValue, GM_xmlhttpRequest) and UserCSS themes applied as native CSS with no JavaScript wrapper. That combination is unusual for a Safari blocker.

It is not for you if your daily browser is Chrome, Firefox or anything on Android. The repository contains no Chrome extension and the README makes no such claim. It is also not a system-wide network filter: it works inside Safari through Apple's content blocking API, not as a VPN or DNS sinkhole.

How the Five Extensions and the Rule Pipeline Fit Together

The repository layout shows the architecture. At the top level there are paired directories: wBlock Ads and wBlock Ads (iOS), wBlock Custom and wBlock Custom (iOS), wBlock Foreign, wBlock Privacy, wBlock Scripts, and wBlock Security. Each pair is a Safari content blocking extension target, one variant for macOS and one for iOS-family platforms. Five categories times two platform variants explains the five-extension claim.

Filter rules are stored with Protocol Buffers and compressed with LZ4. The README states that streaming I/O keeps memory low during compilation, and that idle memory sits around 40 MB because Safari runs rules out of process. Updates use HTTP conditional requests (If-Modified-Since and ETag), so a refresh only downloads what changed rather than the full list.

Custom lists are the escape hatch. wBlock accepts a filter list by URL, by pasting text, or by importing a file, and the README says it supports any AdGuard-syntax blocklist. That matters because it means you are not limited to whatever ships in the app. iCloud sync carries filter selections, custom lists, userscripts and the whitelist across devices, so a rule you add on a Mac appears on the iPhone.

Two other pieces sit outside the blocking rules. wBlock Scripts handles URL tracking-parameter stripping, removing UTM parameters and unwrapping shortener and redirect URLs, and it is enabled by default. Tube Cleaner and Player Cleaner are optional remote userscripts downloaded from a separate wBlock-userscripts repository. The README is explicit that these turn existing media elements into native Safari players before first paint to restore Picture-in-Picture and background playback, and that they update independently of the app version. Ads on those pages are still handled by the content blocking rules, not by the userscripts.

Installing wBlock on macOS with Homebrew, and a First Real Use

There are two install paths. The App Store badge in the README points at the iOS and macOS listing, and the README also gives a Homebrew cask for macOS. The cask route is the one you can script:

brew tap 0xcub3/wblock && brew install --cask wblock

After the cask installs, launch wBlock once. Safari will not block anything until you enable the extensions, because content blockers on Apple platforms are separate extension bundles that the browser has to be told to use. Open Safari, go to Settings, then Extensions, and enable the wBlock entries you want active. The README describes five content blocking extensions per platform, and the rule distribution logic spreads rules across all five slots, so enabling fewer than all of them reduces coverage.

With extensions on, the first practical test is a per-site toggle. The README says you can disable blocking on specific sites from the Safari toolbar. Load a site that breaks under blocking, open the wBlock toolbar popup, and switch blocking off for that domain. That writes to the whitelist, which iCloud sync then propagates to your other devices.

If you want to add a custom list, the README lists three input methods: URL, paste, or file import. Those are the only documented paths, and the README does not describe a configuration file or a command-line flag for adding a list, so treat the app's own screens as the supported route. For the element zapper, the feature is available on macOS, iOS, iPadOS and visionOS according to the README, and it works by letting you visually select a page element to hide. Per-site settings go further than the on/off toggle: the README lists whitelisting trusted domains, toggling userscripts per site, and switching element zapper rules on or off per domain.

Where wBlock Breaks Down or Is the Wrong Choice

The most concrete limitation is update reliability on iOS. The README says auto-updates can run from every hour to every 7 days or be triggered manually, but it also says macOS can keep checking through a bundled launch agent and background update service, while iOS background checks are best-effort. That is an honest admission and a real asymmetry. On an iPhone or iPad, your filter lists may lag behind the source lists, and there is no launch agent to fix it. If you need guaranteed freshness on iOS, you are relying on opening the app yourself.

The second constraint is the platform lock. This is a Safari blocker. Nothing in the repository targets Chrome, Firefox or Android, and the README makes no claim about them. If you switch browsers, wBlock does not follow you.

The third is auditability. wBlock is GPL-3.0 and the source is in the repository, but the README's primary distribution path is the App Store, with a Homebrew cask as the macOS alternative. Building the Xcode project yourself is possible given the wBlock.xcodeproj entry, but the README does not document a build procedure, so a user who wants to verify the exact binary they run has more work to do than the licence alone suggests. That is a gap in the documentation, not a flaw in the licence.

Finally, the element zapper and per-site controls are manual tools. They are good for fixing a broken page once. They are not a substitute for a maintained filter list, and the README does not present them as one.

wBlock Compared with uBlock Origin Lite and Other Safari Blockers

The obvious comparison is uBlock Origin Lite, which is the Manifest V3-compatible rewrite of uBlock Origin and also ships a Safari version. The difference in approach is structural rather than cosmetic. uBlock Origin Lite is built around declarative rulesets that the browser applies, with a deliberately reduced feature set compared with classic uBlock Origin because Manifest V3 removed the blocking webRequest API that the original relied on. wBlock is built directly on Apple's content blocking API, which is also declarative, but wBlock adds a userscript engine with Greasemonkey API calls and native UserCSS support on top of the rule lists.

That is the real dividing line. If you want a filter-list blocker and nothing else, both projects land in a similar place, and the choice comes down to which list ecosystem you prefer. If you want to run userscripts, apply UserCSS themes, and use a visual element zapper inside Safari, wBlock's README documents those features and uBlock Origin Lite's scope is narrower by design.

The other comparison the README itself points to is a comparison guide in the repository, Adblock_Comparison.md, which the author wrote to position wBlock against other Safari content blockers. That file is worth reading directly rather than trusting a summary, since it is the author's own framing.

There is also a naming collision worth flagging. wBlock is the name of an AutoCAD command, and a large share of search traffic for the term belongs to CAD workflows, not to this Safari extension. If you arrived here looking for how to write a block out to a separate drawing file, you are in the wrong place.

Licence, Maintenance and Upgrade Cost

wBlock is GPL-3.0. The practical implication is that if you redistribute a modified version, you have to provide the source under the same terms. It does not restrict private use, and it does not change how the App Store build is distributed. This is a description of the licence identifier in the repository, not legal advice; if you plan to fork and ship something, read the LICENSE file and talk to someone qualified.

Maintenance looks current. The last push to the main branch was on 2026-09-23, and the most recent release listed is 3.1.1 on 2026-09-22, following 3.1.0 on 2026-09-09 and 3.0.0 on 2026-08-29. The repository is not archived. That is a fast release cadence over a short window, which usually means active work, though the README does not publish a support policy or an end-of-life plan for older platform versions.

Upgrade cost is low by design. Auto-update intervals are configurable from every hour to every 7 days, or manual, and the HTTP conditional request handling means an update pulls only the changed portion of the lists. The remote userscripts for Tube Cleaner and Player Cleaner update independently of the app version, so a userscript fix does not require an app release. The one thing to watch on upgrade is iCloud sync: because filter selections, custom lists, userscripts and the whitelist sync across devices, a change made on one platform propagates to the others, and the README does not document a per-device opt-out.

Editorial conclusion

Adopt wBlock if you live in Safari on Apple platforms and want userscripts, userstyles and a visual element zapper without leaving the browser. Skip it if you need Chrome, Firefox or Android coverage, or if you want a blocker you can audit line by line, since the app ships through the App Store rather than as source you compile yourself. Before committing, install the Homebrew cask or App Store build, enable all five extensions in Safari settings, and confirm your platform meets the stated floors of macOS 12.3, iOS 15.4 or visionOS 2.0.

Frequently asked questions

Official sources

1. 0xCUB3/wBlock on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases