AdguardTeam/AdguardBrowserExtension

Ad blocker with advanced privacy protection features

AdGuard is a fast and lightweight ad blocking browser extension
that effectively blocks all types of ads and trackers.

AdGuard.com | Reddit | Twitter | Telegram

AdGuard is a fast and lightweight ad blocking browser extension that effectively blocks all types of ads and trackers on all web pages. We focus on advanced privacy protection features to not just block known trackers, but prevent web sites from building your shadow profile. Unlike its standalone counterparts (AG for Windows, Mac), the browser extension is completely free and open source. You can learn more about the difference here.

AdGuard does not collect any information about you, and does not participate in any acceptable ads program. The only source of income we have is selling premium versions of our software, and we intend to keep it that way.

• Installation
  • Chrome and Chromium-based browsers
  • Firefox
  • Opera
  • Microsoft Edge
• Contribution
  • Translating AdGuard
  • Testing AdGuard
  • Reporting issues
  • Other options
• Development
• Deployment
• Getting Started
• Permissions
• Auto-publish builds
• Versioning Schema
• Minimum supported browser versions
• Documentation

Installation

Chrome and Chromium-based browsers

Install from the Chrome Web Store.

Firefox

Install from the Mozilla Add-ons website.

Opera

Install from the Opera Add-ons store.

Microsoft Edge

Install from the Microsoft Store.

Contribution

We are blessed to have a community that does not only love AdGuard, but also gives back. A lot of people volunteer in various ways to make other users' experience with AdGuard better, and you can join them!

We, on our part, can only be happy to reward the most active members of the community. So, what can you do?

Translating AdGuard

If you want to help with AdGuard translations, please learn more about translating our products here: https://adguard.com/kb/miscellaneous/contribute/translate/program/

Testing AdGuard

You can get a beta version of AdGuard Browser Extension for any browser. All necessary information on this topic can be found on a dedicated page on our website.

Reporting issues

GitHub can be used to report a bug or to submit a feature request. To do so, go to this page and click the New issue button.

[!NOTE] For the filter-related issues (missed ads, false positives etc.) use the dedicated repository.

Other options

Here is a dedicated page for those who are willing to contribute.

Getting Started

After installing the extension from your browser's store:

1. Click the AdGuard icon in the browser toolbar to open the popup. Ad blocking is enabled by default with a recommended set of filter lists.
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" to visually pick and block unwanted page elements.

The extension works out of the box with sensible defaults.

Permissions required

Common permissions for all browsers and manifest versions

• tabs - required to get the URL of the options page tab
• webRequest - required to apply cosmetic rules, detect and remove tracking cookies, and count blocked resources
• cookies - required to delete cookies from requests or change their lifetime
• contextMenus - required to create a context menu
• storage - required to save user settings, user rules, and custom filters
• unlimitedStorage - required to save large filter lists
• webNavigation - required to catch the moment for injecting scriptlets
• privacy - allows access to browser privacy settings; required in Firefox, optional in Chrome/Edge/Opera

Permissions for MV2 only

• <all_urls> - grants access to all websites to apply content scripts and filtering rules
• webRequestBlocking - required to block or modify HTTP requests synchronously

Permissions for MV3 only

• host_permissions - grants access to all websites (MV3 uses this instead of <all_urls>)
• userScripts - required to let the user subscribe to custom filter lists and evaluate rules from these lists
• scripting - required to inject the assistant script into pages
• declarativeNetRequest - required to block, redirect, and modify URL requests
• declarativeNetRequestFeedback - required to create a log of the blocked, redirected, or modified URL requests

Auto-publish builds

Due to the transition from MV2 to MV3, we cannot update our filters remotely. To keep the filters as fresh as possible, we have configured automated tasks in our CI plans. These tasks will build a new version of the extension with only the updated @adguard/dnr-rulesets package, which contains new static rulesets.

Auto-update cycle

We have set up an automated update cycle that regularly syncs with fresh releases from the @adguard/dnr-rulesets npm package. The update frequency is configured in our CI build schedule. This ensures our extension stays up-to-date with the latest filter rules.

To deploy new releases as soon as possible, we have implemented all the steps outlined in Chrome's Skip Review documentation. This allows us to publish updates to the Chrome Web Store without waiting for the full review cycle.

Skip review restrictions

However, there is an important restriction when using the "skip review" option: we cannot update the extension with skip review if it contains changes to filtering script rules. This is because all script rules are collected during build time into a file called local_script_rules.js (for safe use them with the scripting API).

Therefore, any updates that include changes to script rules will require the full review cycle in the Chrome Web Store as usual.

Build process

These automated tasks will run all necessary checks: unit tests, translation checks, and linter. After that, they will update resources, including filters and local script rules, create a build, and run integration tests to ensure the update is safe.

Finally, the new version of the extension will be published to the Chrome Web Store.

Versioning Schema

The extension uses the following versioning schema:

major.minor.patch+autoBuildIncrementVersion.buildTag.dnrRulesetsVersion

• major.minor.patch: Standard semantic versioning for the extension codebase.
• autoBuildIncrementVersion: An incrementing number used as the fourth part of the manifest version (e.g., 88 in 5.2.1.88).
• buildTag: A delimiter indicating the build's readiness.
• dnrRulesetsVersion: The patch version of the DNR rulesets, which includes the build date for those rulesets.

Example: 5.2.1+88.beta.20251014

But for build versions we will use following format: major.minor.patch.autoBuildIncrementVersion to comply with the browser requirements for version.

Minimum supported browser versions

The extension supports both Manifest V2 (MV2) and Manifest V3 (MV3) platforms. MV3 is the newer extension platform required by Chrome and other Chromium-based browsers going forward.

Documentation

• Development — development setup and build instructions
• Changelog — version history
• LLM agent rules — guidance for AI coding assistants