wBlock

A Safari content blocker for macOS, iOS, iPadOS, and visionOS.
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](Adblock_Comparison.md) to see how wBlock stacks up against other Safari content blockers.

### 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 - **No Autoplay** (macOS, iOS, iPadOS, visionOS) — keeps videos and audio paused until you tap or click them, stopping muted feed/scroll autoplay; enable it globally from the Safari toolbar popup and allow autoplay per site when a page needs it - **Tube Cleaner & Player Cleaner** — optional remote userscript defaults downloaded from the wBlock-userscripts repository; they turn existing media elements into native Safari players before first paint, restoring Picture-in-Picture and background playback. They update independently of the app version; wBlock's content-blocking rules handle ads separately - **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. See [docs/USERSTYLES.md](docs/USERSTYLES.md) - **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** - **URL tracking-parameter stripping** — removes UTM and other tracking params, unwraps shortener/redirect URLs (enabled by default via wBlock Scripts) ### 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 - **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`

---

---

**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 - Bundled AdGuard scriptlet engine for advanced blocking techniques - Swift concurrency (async/await, Task, Actor isolation) with project-level Swift 5 settings - VoiceOver and Dynamic Type support throughout the SwiftUI app - SwiftProtobuf for cross-platform filter storage format

---

---
How does wBlock compare to other ad blockers?
Check out our comparison guide vs uBlock Origin Lite, Wipr 2, and AdGuard's Safari apps. Should I install wBlock from the App Store or the DMG/Homebrew release?
The App Store version is usually preferred because it handles app updates automatically. The DMG/Homebrew release has the same features and is available for users who prefer installing outside the App Store. Should I use wBlock alongside another ad blocker?
No. Use one general-purpose content blocker at a time. There is no controlled study proving that every possible combination of ad blockers harms every page. However, browser architecture and extension documentation support avoiding overlapping blockers: - Extensions can make conflicting changes. Mozilla documents that when two extensions attempt conflicting modifications to the same response header, only one change may succeed. Multiple blockers can therefore produce order-dependent behavior rather than a predictable combination of their protections. See Mozilla’s webRequest documentation. - Request interception has measurable computational costs. Chromium describes serialization, inter-process communication, persistent-process, and extension-response processing costs associated with blocking request handlers. Running redundant filtering systems duplicates at least some rule evaluation and page-processing work. See Chromium’s explanation of Web Request and Declarative Net Request and Chrome’s Manifest V3 overview. - Major blocker maintainers explicitly advise against stacking. The official uBlock Origin README states: “Do NOT use uBO with any other content blocker.” It explains that another blocker can prevent uBO’s privacy or anti-blocker-defusing features from working correctly. See uBlock Origin’s official documentation. - Documented failure modes include slower loading and broken functionality. AdGuard warns that two blockers may compete over the same requests, causing slower page loading, broken websites, or video-playback problems. See AdGuard’s guidance. For wBlock specifically, another blocker also makes troubleshooting impossible as well. When an advertisement survives or a site breaks, either blocker’s network rules, cosmetic rules, scriptlets, exceptions, or execution order may be responsible. The second blocker is therefore a confounding variable. Disable all other content blockers before reporting a wBlock issue.
Installing redundant blockers is not defense in depth when both tools compete at the same interception layer. It is an uncontrolled experiment with no control group. 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 cover things the defaults do not. Does wBlock slow down Safari?
No in normal use. wBlock uses Safari's native declarative content blocking API, which applies compiled rules outside the app process. Local idle checks sit around ~40 MB, and page loading stays on Safari's native blocker path. Do userscripts work on iOS and iPadOS?
Yes. The userscript engine implements common Greasemonkey APIs (GM_getValue, GM_setValue, GM_xmlhttpRequest, GM_addStyle) on iOS, iPadOS, and macOS via Safari Web Extensions. `GM_xmlhttpRequest` requires `@grant GM_xmlhttpRequest` or `@grant GM.xmlHttpRequest` and checks the installed script's `@connect` metadata before sending a request. A bare host permits that host and its subdomains. `localhost`, `self` (the current frame's host), and `*` are supported. Scripts without `@connect` can contact only their current host; add explicit hosts for cross-host requests. There is no per-domain permission prompt yet. Only HTTP and HTTPS are allowed, and redirects are checked before following. Safari redirects whose destination is hidden from the extension fail rather than bypass the allow-list. Native requests do not share ambient cookies or saved credentials; an anonymous request also strips explicitly supplied cookies. How do I block Twitch ads?
wBlock bundles the AdGuard Extra userscript, which can help with Twitch ads by talking to Twitch's GraphQL API (gql.twitch.tv) — the same general approach uBlock Origin users rely on. It ships disabled by default, so enable it for Twitch:

1. Open wBlock and go to the Userscripts section.
2. Find AdGuard Extra in the built-in list and toggle it on.
3. 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. What are Tube Cleaner and Player Cleaner?
They are optional remotely downloaded userscripts, inspired by Vinegar and Baking Soda, that expose Safari's native controls on a site's existing media element. They are disabled by default; enable them in the Userscripts section. Their releases are hosted in wBlock-userscripts and are not tied to a wBlock app version.

Tube Cleaner targets YouTube watch, Shorts, and Music pages. It leaves /embed and youtube-nocookie frames to YouTube's own player so those iframes do not go blank. On watch pages it lets YouTube create and initialize its own <video> and SABR/MSE stream, then applies native controls and hides YouTube's custom chrome before it can paint. Hover-to-play thumbnail previews stay with YouTube so they cannot steal the watch player. Reusing the same media element preserves buffering and adaptive playback while restoring Picture-in-Picture and background playback. It mirrors YouTube chapters and subtitles into Safari's native media menus and skips known segments through SponsorBlock's privacy-preserving hash-prefix API. Its compact SB panel provides SponsorBlock-style category colors and per-category Auto skip, Show skip button, or Disabled behavior, plus minimum-duration, Undo-notice, current-video, and channel-exclusion controls. An opt-in DA panel can use DeArrow to replace submitted titles and thumbnails on the watch page and visible YouTube cards, restore originals on hover, or exclude the current channel. Results are session-cached; random fallback thumbnails, title reformatting, submissions, and voting remain features of the