github.com/0xCUB3/wBlock @2.2.0
Chat with this repoWhat it actually does AI analysis from the code graph — generated when you open this
README
wBlock
The end of Safari ad-blocking B.S.
<img src="https://toolbox.marketingtools.apple.com/api/v2/badges/download-on-the-app-store/black/en-us?releaseDate=1760313600" alt="Download on the App Store" width="245" height="82" />
<img src="https://github.com/0xCUB3/wBlock/raw/2.2.0/docs/media/img/hero_image_light.png" alt="wBlock Interface" width="900" />
A Safari content blocker for macOS, iOS, and iPadOS.
750,000 rules across 5 extensions, Protocol Buffer storage, LZ4 compression, and iCloud sync.
[!NOTE] Looking for a detailed comparison? Check out my comparison guide to see how wBlock stacks up against other Safari content blockers.
Features
| ### Performance - **750,000 rule capacity** across 5 Safari content blocking extensions per platform (150k each) - **~40 MB RAM** at idle — Safari's native content blocking API runs rules out-of-process - **Protocol Buffers + LZ4** for filter storage; streaming I/O keeps memory low during compilation - **HTTP conditional requests** (If-Modified-Since/ETag) so updates only download what changed - **iCloud sync** for filter selections, custom lists, userscripts, and whitelist across devices ### Content modification - **Element Zapper** (macOS, iOS, iPadOS, visionOS) — visually select and hide page elements in Safari - **Userscript engine** with Greasemonkey API (GM_getValue, GM_setValue, GM_xmlhttpRequest) - **Userstyle support** — install UserCSS themes (.user.css) applied natively as CSS, no JS wrapper needed - **Custom filter lists** via URL, paste, or file import — supports any AdGuard-syntax blocklist - **Toolbar search** for quickly finding filters and userscripts - **Automatic rule distribution** across all 5 content blocker slots for maximum coverage | ### Blocking - **Network request blocking** — ads, trackers, cookie banners, annoyances - **CSS injection** for cosmetic filtering and element hiding - **Script blocking** for unwanted JavaScript - **Pop-up and redirect prevention** ### Configuration - **Auto-updates** from every hour to every 7 days, or manual. macOS can keep checking through a bundled launch agent and background update service, iOS background checks are best-effort - **Per-site controls** — disable blocking on specific sites from the Safari toolbar - **Blocked request logger** (macOS) — see what's being blocked on each page - **Per-site settings** — whitelist trusted domains, toggle userscripts per site, and switch element zapper rules on or off per domain - **Regional filters** with auto-detection based on your locale - **Homebrew cask** for macOS: `brew tap 0xcub3/wblock && brew install --cask wblock` |
Screenshots
Userscript Management
Manage paywalls, YouTube Dislikes, and more
|
Settings & Customization
Configure auto-updates, notifications, and preferences
|
iOS Interface
Full-featured blocking on iPhone
|
iPadOS Interface
Full-featured blocking on iPad
|
Technical Implementation
| **Core Architecture** - Protocol Buffers (libprotobuf) with LZ4 compression for filter serialization - Asynchronous I/O with Swift concurrency (async/await, Task, Actor isolation) - Streaming serialization to disk minimizes peak memory usage during compilation - 5 Safari content blocking extensions per platform (maximum Safari API capacity) - SafariServices framework integration for declarative content blocking | **Dependencies & Standards** - SafariConverterLib v4.3.0 for AdGuard to Safari rule conversion - AdGuard Scriptlets v2.3.1 for advanced blocking techniques - Swift 5.9+ with strict concurrency checking enabled - WCAG 2.1 AA compliance with full VoiceOver and Dynamic Type support - SwiftProtobuf for cross-platform filter storage format |
Support Development
wBlock is free and open source.
If you want to support the project:
FAQ
How does wBlock compare to other ad blockers?
Check out our comparison guide vs uBlock Origin Lite, Wipr 2, and AdGuard Mini.
Should I install wBlock from the App Store or the DMG/Homebrew release?
The App Store version is generally preferred because it provides automatic app updates. The DMG/Homebrew release has the same features and is available for users who prefer installing outside the App Store.
Can I use my own filter lists?
Yes. You can add any AdGuard-compatible filter list by URL, paste rules directly, or import from a file.
Should I enable more filter lists for better blocking?
Usually not. The recommended defaults already cover most ads and trackers, and most other general-purpose lists overlap with them. Enabling more mainly uses up Safari's rule limit and increases the chance of site breakage. The exceptions are Annoyances filters (cookie banners, popups, social widgets) and regional filters for non-English sites, which block things the defaults don't.
Does wBlock slow down Safari?
No. wBlock uses Safari's native declarative content blocking API, which processes rules in a separate process. Memory overhead is ~40 MB at idle with no measurable impact on page load times.
Do userscripts work on iOS and iPadOS?
Yes. The userscript engine implements the Greasemonkey API (GM_getValue, GM_setValue, GM_xmlhttpRequest, GM_addStyle) on iOS, iPadOS, and macOS via Safari Web Extensions.
How do I block Twitch ads?
wBlock already bundles the AdGuard Extra userscript, which removes Twitch ads by talking to Twitch's GraphQL API (gql.twitch.tv) — the same approach uBlock Origin users rely on. It ships disabled by default, so enable it to block Twitch ads:
-
Open wBlock and go to the Userscripts section.
-
Find AdGuard Extra in the built-in list and toggle it on.
-
Reload any open Twitch tabs.
This is best-effort, community-style ad blocking: Twitch frequently changes how ads are served, so it may occasionally break until the userscript is updated. There is no guarantee every ad is removed.
How often do filters update?
Auto-update intervals are configurable from 1 hour to 7 days, or manually triggered. On macOS, enabling auto-update registers a bundled launch agent that can keep checking while the app is closed through a background update service. On iOS and iPadOS, background checks are best-effort and may wait until the system wakes wBlock or you reopen it. Opening Safari does not trigger updates. Updates use HTTP conditional requests (If-Modified-Since/ETag headers) to minimize bandwidth usage.
Is the element zapper available on iOS and iPadOS?
Yes. Open the wBlock extension popup in Safari and tap Activate Element Zapper.
Credits
@arjpar · @ameshkov · @shindgewongxj
Developed by 0xCUB3
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=0xCUB3/wBlock&type=date&legend=bottom-right" />
Core symbols most depended-on inside this repo
sliceShape
Languages
Modules by API surface
For agents
$ claude mcp add wBlock \
-- python -m otcore.mcp_server <graph>