# Where Are Dynamic Filtering Rules Stored in uBlock Origin? A Deep Dive into the Source Code

> Discover where uBlock Origin stores dynamic filtering rules in its source code. Learn how dynamicNetFilteringString is parsed and used by the extension.

- Repository: [Raymond Hill/uBlock](https://github.com/gorhill/uBlock)
- Tags: deep-dive
- Published: 2026-03-05

---

**Dynamic filtering rules in uBlock Origin are stored as a plain-text string under the key `dynamicFilteringString` in the extension's persistent storage, parsed at startup by the Dynamic Net Filtering engine.**

Unlike static filter lists that reside in external files, dynamic filtering rules in the gorhill/uBlock repository live entirely within the browser's extension storage. These rules—created when you use the popup interface to block or allow domains dynamically—are serialized, persisted, and loaded through a specific pipeline of modules. Understanding this storage mechanism is essential for developers building tools to backup, sync, or programmatically modify uBlock Origin configurations.

## How uBlock Origin Stores Dynamic Filtering Rules

### The Persistent Storage Key: `dynamicFilteringString`

The canonical storage location for user-created dynamic rules is the `dynamicFilteringString` key. In [`src/js/storage.js`](https://github.com/gorhill/uBlock/blob/main/src/js/storage.js), the extension reads and writes this value using the standard storage API:

```javascript
// src/js/storage.js – Reading stored rules
const fetchDynamicRules = async function() {
    const fetched = await vAPI.storage.get('dynamicFilteringString');
    return fetched.dynamicFilteringString || '';
};

```

When users modify rules through the popup interface, the updated string is committed back to storage via the same module. This design ensures that dynamic rules persist across browser restarts without relying on external files.

### Default Rules Defined in [`background.js`](https://github.com/gorhill/uBlock/blob/main/background.js)

If no user-defined rules exist, uBlock Origin falls back to a built-in default set. In [`src/js/background.js`](https://github.com/gorhill/uBlock/blob/main/src/js/background.js), the `dynamicFilteringDefault` array defines these baseline rules:

```javascript
// src/js/background.js – Default dynamic filtering rules
µBlock.dynamicFilteringDefault = [
    'behind-the-scene * * noop',
    'behind-the-scene * 3p-frame noop',
    // ... additional default rules
];

```

During first-run initialization, this default array is joined into a newline-delimited string and written to `dynamicFilteringString`, ensuring that the dynamic filtering engine has a valid rule set to evaluate immediately upon installation.

## Loading and Parsing Dynamic Rules on Startup

When the extension initializes, [`src/js/start.js`](https://github.com/gorhill/uBlock/blob/main/src/js/start.js) orchestrates the loading sequence. The stored `dynamicFilteringString` is retrieved and passed to the filtering engine:

```javascript
// src/js/start.js – Startup initialization
const dynamicRules = µb.storage.getItem('dynamicFilteringString') 
    || µb.dynamicFilteringDefault.join('\n');

// Parse and load into the filtering engine
µb.permanentFirewall.fromString(dynamicRules);

```

The `permanentFirewall` instance is an instantiation of the **Dynamic Net Filtering** engine defined in [`src/js/dynamic-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/src/js/dynamic-net-filtering.js). This engine parses the plain-text rules into internal rule objects capable of evaluating "dynamic host" and "dynamic URL" blocking decisions at runtime. The engine is registered with the main filtering system in [`src/js/filtering-engines.js`](https://github.com/gorhill/uBlock/blob/main/src/js/filtering-engines.js), ensuring that dynamic rules are evaluated alongside static filter lists.

## Editing and Saving Rules Through the UI

User interaction with dynamic rules occurs primarily through the popup interface. The editing pane logic resides in [`src/js/popup-fenix.js`](https://github.com/gorhill/uBlock/blob/main/src/js/popup-fenix.js), which renders the dynamic filtering matrix and handles user clicks.

For text-based editing, uBlock Origin uses a specialized CodeMirror mode defined in [`src/js/codemirror/ubo-dynamic-filtering.js`](https://github.com/gorhill/uBlock/blob/main/src/js/codemirror/ubo-dynamic-filtering.js). This provides syntax highlighting and validation for the dynamic rule format.

When users click **Save**, the edited rule string is committed to storage:

```javascript
// Conceptual flow in popup-fenix.js
function saveDynamicRules(newRulesText) {
    µb.storage.setItem('dynamicFilteringString', newRulesText);
    // Trigger reload of the filtering engine
    µb.permanentFirewall.fromString(newRulesText);
}

```

This immediate persistence ensures that dynamic filtering changes survive browser restarts without requiring manual export.

## Code Examples: Accessing Dynamic Filtering Rules

### Retrieving Rules for Backup

To extract the current dynamic rules for backup purposes, access the storage key directly:

```javascript
// Accessing dynamic rules programmatically
const rules = await browser.storage.local.get('dynamicFilteringString');
console.log(rules.dynamicFilteringString);
// Output: "behind-the-scene * * noop\n* * 3p-frame block\n..."

```

### Loading Custom Rules at Runtime

Developers can programmatically load custom dynamic rules during extension initialization:

```javascript
// src/js/start.js pattern
const customRules = `
    * * 3p-frame block
    * * 3p-script block
    example.com * allow
`;

µb.permanentFirewall.fromString(customRules);
µb.storage.setItem('dynamicFilteringString', customRules);

```

### Debugging the Rule Engine

To inspect which dynamic rules are currently active in the filtering engine:

```javascript
// Accessing the parsed rule collection
const firewall = µb.permanentFirewall;
console.log('Dynamic rules count:', firewall.rules.size);
// Iterate through rules
for (const [key, rule] of firewall.rules) {
    console.log(key, rule.action);
}

```

## Summary

- **Dynamic filtering rules** in uBlock Origin persist as a plain-text string under the storage key `dynamicFilteringString`, managed in [`src/js/storage.js`](https://github.com/gorhill/uBlock/blob/main/src/js/storage.js).
- **Default rules** are defined as an array in [`src/js/background.js`](https://github.com/gorhill/uBlock/blob/main/src/js/background.js) and converted to the storage format during first-run initialization.
- **Startup loading** occurs in [`src/js/start.js`](https://github.com/gorhill/uBlock/blob/main/src/js/start.js), which retrieves the stored string and populates the **Dynamic Net Filtering** engine ([`src/js/dynamic-net-filtering.js`](https://github.com/gorhill/uBlock/blob/main/src/js/dynamic-net-filtering.js)).
- **User interface** editing is handled by [`src/js/popup-fenix.js`](https://github.com/gorhill/uBlock/blob/main/src/js/popup-fenix.js) and [`src/js/codemirror/ubo-dynamic-filtering.js`](https://github.com/gorhill/uBlock/blob/main/src/js/codemirror/ubo-dynamic-filtering.js), with changes written immediately back to persistent storage.

## Frequently Asked Questions

### How do I backup my dynamic filtering rules in uBlock Origin?

Export your rules by accessing the **Dashboard** → **My rules** tab, where you can copy the dynamic filtering rules text. Alternatively, programmatically retrieve the `dynamicFilteringString` key from `browser.storage.local` using the extension's background page console. The rules are stored as plain text, making them portable across installations.

### What is the difference between dynamic filtering rules and static filter lists?

**Dynamic filtering rules** are user-created, site-specific exceptions or blocks created through the popup interface, stored in `dynamicFilteringString`, and evaluated by the Dynamic Net Filtering engine. **Static filter lists** are external text files (like EasyList) containing thousands of pattern-based filters, updated remotely, and compiled into optimized filter engines. Dynamic rules take precedence over static filters when conflicts occur.

### Can I edit dynamic filtering rules manually?

Yes. Navigate to the **uBlock Origin Dashboard** → **My rules** tab to edit the raw text of your dynamic filtering rules. The editor uses a specialized CodeMirror mode ([`src/js/codemirror/ubo-dynamic-filtering.js`](https://github.com/gorhill/uBlock/blob/main/src/js/codemirror/ubo-dynamic-filtering.js)) that provides syntax highlighting for the rule format. Each line follows the pattern `hostname source destination action`, such as `* * 3p-frame block`. Changes are saved immediately to the extension's persistent storage.

### Why don't dynamic filtering rules sync across devices?

Dynamic filtering rules are stored in the extension's **local** storage (`browser.storage.local`) under the key `dynamicFilteringString`, not in synchronized storage (`browser.storage.sync`). This design choice prioritizes performance and privacy, keeping potentially sensitive site-specific blocking decisions on the local device. To sync rules across devices, you must manually export the text from the **My rules** panel and import it on your other installations.