Skip to content

Document optional install_url (AMO) and runtime host settings in ExtensionSettings #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkaply merged 1 commit into from
Jul 21, 2026
+6 −3
Merged

Document optional install_url (AMO) and runtime host settings in ExtensionSettings #232

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions src/content/docs/reference/policies/ExtensionSettings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,10 @@ The configuration for each extension is a dictionary that can contain the fields
Valid values:
- `allowed`: Allows the extension to be installed by the user. This is the default behavior. There is no need for an `install_url`; it will automatically be allowed based on the ID.
- `blocked`: Blocks installation of the extension and removes it from the device if already installed. If used in the default (`"*"`) configuration, it blocks all extensions that do not have an explicit configuration with a different `installation_mode`.
- `force_installed`: Automatically installs the extension and prevents it from being removed by the user. This option is not valid for the default configuration and requires an `install_url`. (As of Firefox 152, force-installed extensions are always updated automatically, regardless of the `updates_disabled` setting.)
- `normal_installed`: Automatically installs the extension but allows it to be disabled by the user. This option is not valid for the default configuration and requires an `install_url`.
- `force_installed`: Automatically installs the extension and prevents it from being removed by the user. This option is not valid for the default configuration and requires an `install_url` (as of Firefox 153, the `install_url` is optional for extensions hosted on [addons.mozilla.org](https://addons.mozilla.org); see `install_url`). (As of Firefox 152, force-installed extensions are always updated automatically, regardless of the `updates_disabled` setting.)
- `normal_installed`: Automatically installs the extension but allows it to be disabled by the user. This option is not valid for the default configuration and requires an `install_url` (as of Firefox 153, the `install_url` is optional for extensions hosted on [addons.mozilla.org](https://addons.mozilla.org); see `install_url`).
- `install_url`: The URL from which Firefox can download a `force_installed` or `normal_installed` extension. Firefox automatically installs, updates, or re-installs the extension when the XPI file's internal [`version`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) changes.
- As of Firefox 153, `install_url` is optional. When it is omitted for a `force_installed` or `normal_installed` extension, Firefox installs the latest version from [addons.mozilla.org](https://addons.mozilla.org) using the extension's ID.
- If installing from `addons.mozilla.org`, use `https://addons.mozilla.org/firefox/downloads/latest/ADDON_ID/latest.xpi` and substitute **ADDON_ID** with the extension's ID (for example, `uBlock0@raymondhill.net` or `{446900e4-71c2-419f-a6a7-df9c091e268b}`).
Using the AMO ID ensures Firefox always downloads the latest version that matches the user's platform.
- If installing from the local file system, use a [`file:///` URL](https://en.wikipedia.org/wiki/File_URI_scheme). Firefox will update or re-install the extension whenever the XPI file at that path changes. You can also manually trigger an update by changing the file name or path.
Expand All @@ -55,6 +56,8 @@ The configuration for each extension is a dictionary that can contain the fields
- `"theme"`
- `blocked_install_message`: Maps to a string specifying the error message to display to users if they're blocked from installing an extension. This allows you to append text to the generic error message, for example to direct users to a help desk or explain why an extension is blocked. This setting can be used only for the default configuration.
- `restricted_domains`: An array of domains on which content scripts can't be run. This setting can be used only for the default configuration.
- `runtime_blocked_hosts`: (Firefox 153) An array of hosts, specified as [match patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), on which the extension is not allowed to run. This blocks the extension from injecting content scripts into, or sending requests to, matching hosts. Match patterns must not contain a path component (for example, `*://*.example.com` is valid, but `*://*.example.com/*` is not). Can be set for a specific extension or, using the `"*"` ID, for all extensions.
- `runtime_allowed_hosts`: (Firefox 153) An array of hosts (as match patterns) on which the extension is allowed to run, overriding any matching entries in `runtime_blocked_hosts`. The same path restriction applies. Can be set for a specific extension or for all extensions using `"*"`.
- `updates_disabled`: (Firefox 89, Firefox ESR 78.11) Boolean that indicates whether to disable automatic updates for an individual extension. As of Firefox 152, setting this to `false` forces automatic updates to stay enabled and prevents the user from disabling updates for the extension in the Add-ons Manager.
- `default_area`: (Firefox 113) String that indicates where to place the extension icon by default. Possible values are `navbar` and `menupanel`.
- `temporarily_allow_weak_signatures`: (Firefox 127) Boolean that indicates whether to allow installing extensions signed using deprecated signature algorithms.
Expand All @@ -64,7 +67,7 @@ The configuration for each extension is a dictionary that can contain the fields
An extension that requires one of these permissions cannot be installed, and is disabled if it is already installed.
Optional permissions matching the list that were previously granted are revoked, and calls to `permissions.request()` for a blocked permission are rejected.
Host permissions (such as `<all_urls>` or match patterns) and internal permissions are ignored.
- `allowed_permissions`: (Firefox 154) An array of [API permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) that are exempted from `blocked_permissions` within the same configuration.
- `allowed_permissions`: (Firefox 153) An array of [API permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) that are exempted from `blocked_permissions` within the same configuration.
A per-extension `allowed_permissions` carves out exceptions to that extension's own `blocked_permissions`.
Setting `allowed_permissions` in the default (`"*"`) configuration has no effect.

Expand Down