AdGuard Browser Extension: a free, GPL-3.0 ad blocker for Chrome, Firefox, Opera and Edge

What the AdGuard extension actually covers that a hosts file cannot

A hosts file or DNS-level blocker works at the name-resolution layer. It can drop requests to known ad and tracker domains, and that is the end of its reach. The AdGuard browser extension operates inside the page and inside the request lifecycle, which lets it do three things a resolver cannot.

First, cosmetic filtering. The README's Getting Started section describes an Assistant reachable from the toolbar icon, with an option to "Block an element on this page" that lets you visually pick an element and hide it. That is a CSS-level operation on the DOM, not a network block, so it catches first-party ads served from the site's own domain.

Second, cookie handling. The extension requests the cookies permission, which the README says is used "to delete cookies from requests or change their lifetime." A DNS blocker sees a request to a tracking endpoint but cannot rewrite the Set-Cookie header that accompanies a first-party response.

Third, scriptlet injection. The webNavigation permission is listed as required "to catch the moment for injecting scriptlets." Scriptlets are small scripts injected before page scripts run, used to neutralize anti-adblock detectors and tracking code that would otherwise execute.

The intended user is someone browsing in Chrome, Chromium, Firefox, Opera or Edge who wants filtering inside the page and does not want to install a system-wide application. The README is explicit that the browser extension is free and open source, unlike the standalone Windows and macOS products, and links to a comparison page for the difference.

Permissions are the architecture: MV2 and MV3 are two different products

The README's permissions section is the most informative part of the repository for anyone evaluating the extension, because it shows that the same feature set is implemented twice against two incompatible browser models.

The common permissions across all browsers and manifest versions are tabs, webRequest, cookies, contextMenus, storage, unlimitedStorage, webNavigation and privacy. The README notes that privacy is "required in Firefox, optional in Chrome/Edge/Opera," which is a small but real divergence in behaviour between engines.

MV2 gets two additional permissions: <all_urls>, which "grants access to all websites to apply content scripts and filtering rules," and webRequestBlocking, which is "required to block or modify HTTP requests synchronously." The word synchronously matters. In MV2 the extension can inspect a request and decide to cancel it before it leaves the browser.

MV3 does not get webRequestBlocking. The README's MV3 list begins with host_permissions, and the repository carries separate tsconfig.mv2.json and tsconfig.mv3.json files plus separate test projects (test:mv2 and test:mv3 in package.json). The package.json also has a resources:mv3 script that installs @adguard/dnr-rulesets and a related resources:mv3:extract-unsafe-rules script invoking dnr-rulesets exclude-unsafe-rules against ./Extension/filters/chromium-mv3/declarative. That path name, declarative, is the giveaway: on MV3 the filtering rules are compiled ahead of time into declarativeNetRequest rulesets rather than evaluated at request time.

The practical consequence is that MV3 builds are constrained by what declarative rules can express. The existence of an "exclude-unsafe-rules" step suggests the toolchain deliberately drops rules that cannot be safely represented in the declarative format. The README does not enumerate which rule types are lost, so that is something to verify against the filter lists you depend on rather than assume.

Installing AdGuard from a browser store and blocking your first element

There is no build step for normal use. The README points at four store listings: the Chrome Web Store, Mozilla Add-ons, the Opera Add-ons store and the Microsoft Store. Each section of the Installation heading is a single link. If you are on a Chromium browser, the Chrome Web Store entry is the one to use; on Firefox, Mozilla Add-ons.

After installation, the README's Getting Started section gives four steps. Ad blocking is on by default with a recommended set of filter lists, so there is nothing to configure before it starts working.

The toolbar popup is where you toggle protection per site. The README describes the main switch in the popup as turning protection on or off for the current website, and the gear icon as opening the full options page:

1. Click the AdGuard icon in the browser toolbar to open the popup.
2. Toggle protection on or off for the current website using the main switch in the popup.
3. Open settings by clicking the gear icon in the popup to access the full options page.
4. Use the Assistant: click the AdGuard icon, then select "Block an element on this page".

For element hiding, the README describes the Assistant path: click the AdGuard icon, then select "Block an element on this page," then pick the element visually. The result is stored as a user rule, which the storage permission description confirms is persisted ("required to save user settings, user rules, and custom filters").

Building from source is a different exercise. The repository is a pnpm workspace (pnpm-workspace.yaml, pnpm-lock.yaml) with a Dockerfile that pins Playwright v1.53.2-noble as the base image and installs [email protected] globally. The package.json scripts include dev, dev:watch, dev:watch:ff, beta and release, all of which shell out to tools/bundle.ts. The Dockerfile also documents a tsurlfilter-build stage that compiles @adguard/tswebextension from a named build context and is skipped entirely when that context is empty, in which case the npm-published versions from package.json are used instead. The README defers build detail to DEVELOPMENT.md and DEPLOYMENT.md, which are separate files in the repository root.

Where the extension is the wrong tool

The extension only filters what the browser requests. Anything outside the browser is untouched: desktop applications, mobile apps, smart-TV clients, IoT devices, and any traffic from another browser profile where the extension is not installed. AdGuard's own product line addresses that gap with standalone applications and DNS, but those are different products with different licences, and the README's comparison link is the place to check the difference rather than assuming the extension covers it.

The MV3 permission model is the second boundary. Without webRequestBlocking, request cancellation happens through declarative rules compiled at build time. A filter rule that depends on runtime state, on a response body, or on a request pattern the declarative format cannot express will not behave the same way on MV3 as on MV2. The repository's resources:mv3:extract-unsafe-rules script indicates the build pipeline actively removes rules it considers unsafe to convert, but the README does not say how many or which categories. If your filtering depends on a specific custom rule, test it on your target browser's manifest version before relying on it.

Third, the extension is not a privacy tool for someone who wants zero network exposure. It requests webRequest, cookies, tabs, webNavigation and, on MV2, <all_urls>. Those permissions are what make filtering possible, but they also mean the extension can see request metadata and cookie operations across every site. The README states the project does not collect information about users and does not participate in an acceptable ads program, and that revenue comes from selling premium versions of other software. That is a policy statement, not an auditable claim, and the GPL-3.0 source is what you would inspect if you needed to verify it.

AdGuard extension versus uBlock Origin and DNS-level blocking

The closest comparison is uBlock Origin, another browser extension that blocks ads and trackers. The architectural difference visible in this repository is the build pipeline. AdGuard maintains a TypeScript monorepo with a shared @adguard/tswebextension package, a separate declarative ruleset package (@adguard/dnr-rulesets) for MV3, dual tsconfig targets, and a Docker-based CI image. uBlock Origin's approach to MV3 has been a separate codebase rather than a shared one, which is a different answer to the same problem: AdGuard pays the cost of maintaining one product across two manifest models, and gets consistent behaviour across browsers in return.

The second difference is scope. AdGuard ships standalone applications and a DNS service alongside the extension, so a user who outgrows browser-only filtering has a migration path within the same vendor. uBlock Origin is browser-only. If you need to filter a device that has no browser, that difference decides the choice.

The third is licensing. This repository is GPL-3.0. uBlock Origin is also GPL-licensed, so neither is a permissive-licence option. If you are embedding a blocker in a proprietary product, both are the wrong starting point; the extension's GPL-3.0 licence means derivative distributions carry source-disclosure obligations. This is a description of the licence file in the repository, not legal advice, and the LICENSE file at the repository root is what governs.

Release cadence, versioning and what you inherit

The repository's last push was on 2026-08-31, and the most recent releases are v5.5.2.3 on 2026-08-26, v5.5.2.3-beta on the same day, and v5.5.1.0 on 2026-08-21. The package.json version string is 5.5.2+3.build.20260825090125, which shows the build metadata format: a semver core, a build counter, and a timestamp. The README has a Versioning Schema section, though its contents are not reproduced here.

For a user installing from a store, upgrade cost is near zero. Store updates are automatic and user rules and custom filters persist through the storage permission. The README does not document a rollback path if a release breaks a site you depend on, so the practical fallback is toggling protection off for that site from the popup while waiting for a fix.

For a contributor or a fork, the cost is higher. The Dockerfile shows the build depends on a Playwright image, a pinned pnpm version, and optionally a sibling checkout of tsurlfilter built through lerna with --scope=@adguard/tswebextension --scope=@adguard/dnr-rulesets --include-dependencies. The .env.example lists two variables, ARTIFACTORY_DOMAIN for blocking-page downloads and OPENAI_API_KEY for checking dangerous script rules, which means a full build in the project's own CI environment expects credentials that an outside contributor will not have. The README does not describe how to build without them.

GPL-3.0 applies to the source. If you redistribute a modified extension, the licence's source-availability terms apply to your distribution. Whether a particular modification triggers that obligation is a question for a lawyer, not for this article.

Editorial conclusion

Adopt it if you want a store-installed ad blocker on Chromium or Firefox and are willing to accept that MV3's host_permissions model limits what any extension can do. Do not adopt it if you need system-wide filtering outside the browser, or if you intend to ship a modified build without reading GPL-3.0's source-disclosure terms. Before installing, check the permissions list in the README against your browser's manifest version, and confirm the current release on the GitHub releases page rather than trusting a store listing's version string.

Frequently asked questions

Official sources

1. AdguardTeam/AdguardBrowserExtension on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases