1. Mozilla
  2. Add-ons
  3. Browser extensions
  4. JavaScript APIs
  5. proxy
  6. proxy.settings

proxy.settings

A BrowserSetting object used to change the browser's proxy settings.

Note: Changing proxy settings requires private browsing window access because proxy settings affect private and non-private windows. Whether an extension can access private browsing windows is under user control. See Extensions in Private Browsing for details. Your extension can check whether it has access to private browsing windows using extension.isAllowedIncognitoAccess. If your extension doesn't have private window permission, calls to proxy.settings.set() throw an exception.

The underlying value is an object. When setting this object, all properties are optional. Any omitted properties are reset to their default value.

autoConfigUrl Optional

string. A URL to use to configure the proxy.

autoLogin Optional

boolean. Don't prompt for authentication if the password is saved. Defaults to false.

ftp Optional

string. The address of the FTP proxy. Can include a port.

http Optional

string. The address of the HTTP proxy. Can include a port.

httpProxyAll Optional

boolean. Use the HTTP proxy server for all protocols. Defaults to false.

passthrough Optional

string. A comma-separated list of hosts that shouldn't be proxied. Can be defined as:

  • HOST_NAME[:PORT], for example: example.com or example.com:1234
  • IP_LITERAL[:PORT]
  • IP_LITERAL/PREFIX_LENGTH_IN_BITS, using CIDR notation
  • <local>, to bypass proxying for all hostnames that don't contain periods.

You can use IPv6 addresses. For example, [::123].

Hosts localhost, 127.0.0.1, and [::1] are never proxied.

proxyDNS Optional

boolean. Whether to proxy DNS when using a SOCKS proxy. Defaults to true when using SOCKS5 and false when using SOCKS4. Prior to Firefox 128, it defaulted to false for SOCKS4 and SOCKS5.

proxyType Optional

string. The type of proxy to use. This may take: "none", "autoDetect", "system", "manual", "autoConfig". Defaults to "system".

socks Optional

string. The address of the SOCKS proxy. Can include a port.

socksVersion Optional

integer. The version of the SOCKS proxy. May be 4 or 5. Defaults to 5.

ssl Optional

string. The address of the TLS/SSL proxy. Can include a port.

Examples

js
let proxySettings = {
  proxyType: "manual",
  http: "http://proxy.org:8080",
  socksVersion: 4,
  passthrough: ".example.org",
};

browser.proxy.settings.set({ value: proxySettings });

Browser compatibility

Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
settings
Chrome – No support
Chrome
footnote No support
Edge – No support
Edge
footnote No support
Firefox – Full support
Firefox 60 (Release date: 2018-05-09)
footnote
footnote From version 88, the ftp setting has no effect because FTP is no longer supported (see bug 1626365).
Opera – No support
Opera
footnote No support
Safari – No support
Safari
footnote No support
Firefox for Android – No support
Firefox for Android
footnote
footnote The object is defined but any attempt to read or modify the setting throws an exception.
footnote See bug 1725981
Safari on iOS – No support
Safari on iOS
footnote No support

Tip: you can click/tap on a cell for more information.

Full support
No support
See implementation notes.

This page was last modified on by MDN contributors.

Visit Mozilla Corporation’s not-for-profit parent, the Mozilla Foundation.
Portions of this content are ©1998–2026 by individual mozilla.org contributors. Content available under a Creative Commons license.