Browser Extension Manual

  1. Home
  2. Browser Extension Help
  3. Browser Extension Manual

Much of this article is specific to FoxyProxy Standard 4.5.6 and earlier, and FoxyProxy Basic 3.5.6 and earlier. Those versions are no longer supported as November 2017.


  • What is FoxyProxy?

    FoxyProxy is a browser extension that automatically switches an internet connection across one or more proxy servers based on URL or IP patterns. Put simply, FoxyProxy automates the manual process of editing the browser’s Network Settings. Proxy server switching occurs based on the loading URL and the switching rules you define.

  • What is a proxy server?

    Please read this excellent article.

  • Does FoxyProxy support proxy auto-configuration (PAC)?

    Yes. See this section for more information.

  • What if I define a proxy in the browser’s network settings?

    FoxyProxy ignores browser network settings unless FoxyProxy is completely disabled.

  • What happens if a proxy goes down? Does FoxyProxy try another proxy?

    No. FoxyProxy will not fail over to another proxy. Instead, the URL(s) simply won’t load. The only exception to this rule are proxies which use automatic proxy configuration (PAC) files that specify proxy failovers.

  • Many web pages are composed of images, javascript files, and CSS files from different URLs. How does FoxyProxy handle this?

    All of the component parts of a webpage are routed through FoxyProxy and subjected to its rules engine. If part of a webpage doesn’t match any patterns, it is loaded through whichever proxy server (or none) is defined for the “Default” proxy. Some people consider this a privacy leak. However, please note that you define a nonsense IP/port for the “Default” proxy (e.g., localhost:64111); then unmatched patterns simply fail to load. Here is our tutorial on writing patterns. The last section explains advanced routing — how to find the URLs needed to load specific pages or websites through a proxy and not other proxies.

  • Where are FoxyProxy’s settings stored?

    FoxyProxy for Chrome stores its settings using Chrome storage. This allows synchronization of settings across multiple Chrome instances. In Firefox, FoxyProxy stores its settings in a file called foxyproxy.xml. By default, it is located in the Firefox Profile directory, but you can direct FoxyProxy for Firefox to use any directory and filename you like by changing the Settings Storage Location in the FoxyProxy Global Settings Tab.

  • Firefox only. Why don’t the
    preferences change when I use FoxyProxy? Why are my changes to those preferences ignored?

    FoxyProxy doesn’t work by reading/writing Firefox preferences. This is not an efficient mechanism for real-time proxy switching.

  • Firefox only. Why does FoxyProxy enable network.dns.disablePrefetch?

    DNS prefetching is a feature of Firefox which increases page-load performance. You can read about it
    here. FoxyProxy disables DNS prefetching under certain
    conditions. It does this because DNS prefetching does not respect proxy rules. In other words, if DNS pretching is enabled but
    you want DNS lookups to occur through a proxy server, you’re out-of-luck. As of FoxyProxy 2.21, DNS prefetching is disabled

    1. FoxyProxy is not disabled


    2a. FoxyProxy is set to “Use Proxy XXXX for All URLs”. Proxy XXXX has the checkbox (on the “General” tab) “Perform remote DNS lookups on hostnames loading through this proxy” checked


    2b. FoxyProxy is set to “Use proxies based on the pre-defined patterns and priorities”. One or more of the ENABLED proxies have the checkbox (on the “General” tab) “Perform remote DNS lookups on hostnames loading through this proxy” checked. An enabled proxy is one whose “Enabled” checkbox is checked (this checkbox is also on the General tab)

    Earlier versions of FoxyProxy disabled this preference indiscriminantly.

  • Where can I get help or request a new feature?

    Please see the various means to contact us and the FoxyProxy community here.

  • Under what license are the FoxyProxy extensions released?

    The FoxyProxy source code is released under the GPL license. The FoxyProxy name, logo, graphics, art work, website, styles, and documentation are proprietary works and are NOT open-source.

The FoxyProxy Rules Engine: Whitelists, Blacklists, and Patterns

This section does not apply to FoxyProxy Basic. FoxyProxy Basic does not support patterns.

Please refer to the pattern tutorial for instructions on writing FoxyProxy patterns. The last section explains how to find the URLs needed to load specific pages or websites through one specific proxy and not other proxies.

  • What are patterns?

    FoxyProxy patterns are rules that define a group of URLs. These rules
    are expressed with wildcards or regular expressions.
    For example, http://** is wildcard pattern that defines all HTTP (but not HTTPS) URLs that are subdomains of
    The FoxyProxy rules engine uses the patterns you define to determine which URLs should be loaded through proxies and which should be
    loaded through a direct internet connection. Here is our tutorial on writing patterns. The last section explains advanced routing — how to find the URLs needed to load specific pages or websites through one specific proxy and not other proxies.

  • What are whitelist patterns?

    Whitelist patterns represent all URLs that should be loaded through a proxy.

  • What are blacklists patterns?

    Blacklist patterns define URLs that should not be loaded through a proxy.

  • Can you summarize how FoxyProxy matching works?

    If FoxyProxy is set to Use Proxies based on their pre-defined patterns and priorities, FoxyProxy matching working this way:

    1. FoxyProxy attempts to match each URL against the whitelist patterns for each proxy in descending order from top to bottom.
    2. A URL matches a whitelist pattern for a proxy IF AND ONLY IF there isn’t a blacklist pattern for that same proxy which does not also match the URL. In other words, if a whitelist and blacklist pattern both match a URL, the blacklist “wins” and the URL is not regarded as matched.
    3. URLs that don’t match any whitelist pattern are loaded by the Default proxy settings. The Default proxy settings may or may not be configured to use your direct internet connection; this is up to you. Read more about the Default proxy below.

    If FoxyProxy is set to Use proxy “xyz” for all URLs, FoxyProxy matching working this way:

    1. All URLS are loaded through proxy “xyz” regardless of blacklists or whitelists.
  • Where can I learn how to write patterns?

    Here is our tutorial on writing patterns. The last section explains advanced routing — how to find the URLs needed to load specific pages or websites through one specific proxy and not other proxies.

  • I’ve defined blacklists and whitelists but FoxyProxy ignores them. Help!

    FoxyProxy only respects patterns when it is set to “Use proxies based on their pre-defined patterns and priorities”. When
    set to any other mode, such as “Use proxy ABC for all URLs”, all patterns — black and white — are ignored. The solution to this problem is to change FoxyProxy to “Use proxies based on their pre-defined patterns and priorities”.

  • FoxyProxy is set to “Use proxies based on their pre-defined patterns and priorities” but still ignores my blacklists. Why?

    There are two possibilities here.

    One: You’re not using the right pattern syntax. Patterns such as localhost or are invalid when used with FoxyProxy. All wildcard patterns should terminate with *. For example, if you are trying to prevent all localhost URLS from using a proxy, use these blacklist wildcard patterns: *localhost/* and

    Two: I need to disable proxy routing when I go to addresses like I created URL pattern ** and switch entry to “Blacklist” option but there’s no effect on routing.

    Make sure you follow these steps (#3 and #4 are often forgotten):

    1. Define proxy using “Add New Proxy” button. Enter details on Proxy Details tab.
    2. On URL Patterns tab, enter blacklist pattern, like **
    3. Be sure to enter a enter whitelist pattern so that other URLs do load through the proxy. For example, use * to MATCH EVERYTHING.
    4. Set FoxyProxy to “Use proxies based on their pre-defined patterns and priorities”

    You can confirm that is NOT going through the proxy by turning on Logging (Logging tab -> Enabled checkbox, use Refresh button after visiting

    Other problems/questions with patterns? Be sure to read this.

  • What is the Default proxy?

    The Default Proxy defines the settings used to load any resource or web page that doesn’t match a whitelisted pattern. In other words, the Default Proxy is a catchall. When first installed, FoxyProxy automatically configures the Default Proxy so that pages load through your direct internet connection (i.e., it’s not using a proxy at all). However, you can change this setting to use any proxy server or PAC file you like, just like any other proxy settings in FoxyProxy.

  • What happens if more than one pattern matches a URL?

    If two or more patterns for different proxies match a URL, the proxy which is ordered higher (from top to bottom) is used to load that URL. This is what is meant by priorities in FoxyProxy. You can reorder proxy priorities with the FoxyProxy Move buttons. The Default Proxy always matches all URLs and cannot be moved. In this sense, the Default Proxy is a catchall.

  • There are many flavors of regular expression syntax (grep, egrep, awk, sed, vim, perl, pure posix, etc). Which one should I use for FoxyProxy?

    FoxyProxy adheres to the JavaScript 1.5 regular expression syntax. When in doubt, refer to this guide. Do not surround regular expressions with forward slashes like this: /abc/

  • What happens if a URL matches both a whitelist pattern and blacklist pattern for the same proxy?

    Blacklist patterns have priority over whitelist patterns. In this scenario, the URL is not loaded through the proxy.
    It is compared with the patterns of other proxies further down the list, including the Default, until a matching pattern
    is found. Note the Default proxy matches all URLs (i.e., it uses the whitelist wildcard pattern *)

  • How can I match all URLs?

    Use this wildcard pattern: *

  • How can I match URLs by protocol?<

    Use wildcard patterns of this style: http://*, ftp://*, feed://*, etc.

  • How can I match URLs by file extension?

    Use this regular expression pattern .*\.(?:bz2|gz|rar|zip|tgz|bundle|deb|pdf|run)$ The $ ensures that no other characters follow the extension.

  • Why doesn’t my whitelist/blacklist pattern match a URL?

    Ensure that your pattern matches the entire URL. For example, if you want to match, you can’t write the regular expression ^https?://google\.com. You must write ^https?://google\.com.*.

  • Do I have to specify every subdomain of a website in my list of patterns? I want*,*, and* to load through a proxy. Must I write a pattern for each?

    No. You can use the whitelist regular expression pattern http://.*\.?google\.com/.*. If you want all protocols to load through the proxy — not just http, then use the regular expression pattern .*://.*\.?google\.com/.* or (.*\.)*google\.com/.*. You can substitute other domains for

  • How can I use different proxies based on my IP address?

    Get FoxyProxy Plus!

  • How can I prevent proxy use on my intranet (local network) and on my local computer (

    Look for the checkbox “Do not use this proxy for internal IP addresses” in the Proxy Settings window, URL Patterns tab.

PAC files

  • What is a proxy auto-configuration (PAC) and where can I read more about them?

    A PAC is a text file containing a small piece of logic which determines how URLs are loaded by the browser. It is comprised of a single javascript function FindProxyForURL(url, host) that you implement. This function returns a string with one or more proxies. Multiple proxies provide a fallback when a proxy fails to respond. An example of a PAC file is:

    function FindProxyForURL(url, host){
      if (shExpMatch(host, "**")) {
        return "PROXY;DIRECT;"
      else if (shExpMatch(host, "**")) {
        return "SOCKS;"
      else {
        return "DIRECT";

    Proxy auto-configuration files are described in complete detail here and here.

  • When does FoxyProxy use my PAC file?

    When you configure a proxy in FoxyProxy and select “Automatic proxy configuration URL” on the “Proxy Details” page, you’re specifying that FoxyProxy use a PAC for any patterns associated with this proxy configuration. In other words, for each URL that matches a URL pattern defined by a proxy configuration specified to use a PAC, FoxyProxy calls that PAC’s FindProxyForURL() implementation. The return value of FindProxyForURL() determines which proxy (if any) is used.


  • How does FoxyProxy secure my privacy?

    FoxyProxy does not inherently secure your privacy or anonymize you. FoxyProxy does not change/mask/hide your IP address without a proxy server.
    Privacy and anonymity are dependent upon a number of factors, including but not limited to the proxy servers you use. Please be careful using FoxyProxy if you are expecting complete anonymity because some have argued that FoxyProxy — when used in patterns mode (identified when the FoxyProxy icon is orange and the “Use proxies based on their pre-defined patterns and priorities” text) — can actually make you more susceptible to privacy breaches.

    The crux of the issue is this. Most web pages are comprised of resources from multiple domains. When FoxyProxy is used in patterns mode, unless you define whitelist patterns which match all resources on a page, then some of those resources won’t load through proxies. The easiest way around this issue is to change FoxyProxy’s mode from patterns to dedicated. In dedicated mode (identified by the blue FoxyProxy icon and the Use proxy “xyz” for all URLs text), FoxyProxy ignore all patterns, loading all resources through a single proxy.

    Patterns mode is one of FoxyProxy’s greatest strengths and is what sets FoxyProxy apart from most other proxy extensions. However, it can also be its greatest weakness if not used appropriately. If you are using a proxy for complete privacy and anonymity, there are two recommended ways to use FoxyProxy so this privacy and anonymity is maintained:

    • Forego patterns and use FoxyProxy in dedicated (non-patterns) mode; i.e., “Use Proxy XXX for all URLs”. This is indicated by the blue FoxyProxy icon in the toolbar.
    • Use FoxyProxy in patterns mode but change the settings for the Default Proxy from using your direct internet connection to a bogus (i.e., non-existent) proxy such as localhost:55555. When a URL is reached which doesn’t match a whitelisted pattern, the URL will attempt load through this non-existent proxy. The attempt will time out and fail. In this way, you can still leverage patterns but not compromise privacy and anonymity.
  • OK, but can I surf the web anonymously with FoxyProxy?

    Yes. Please read the Tor section of this FAQ. I also urge you to read the question How does FoxyProxy secure my privacy?

  • Are there any tutorials on FoxyProxy and privacy?


  • Can DNS lookups go through my proxies?

    Yes. Ensure the following:

    • The proxy in use must support SOCKS 4a or SOCKS 5.
    • Check “Use this proxy for all DNS lookups” on the Proxy Details Tab.
    • Do not use add-ons like Google Toolbar that interfere with remote DNS lookups.


  • What is the relationship between FoxyProxy and Tor?

    There is a common misunderstanding that Tor is required to use FoxyProxy. This is not true. FoxyProxy has nothing to do with Tor. FoxyProxy is not Tor. FoxyProxy does not require Tor. If used with Tor, FoxyProxy efficiently loads only the URLs you define through the slow Tor network. All other URLs load through your direct internet connection or other proxies, as you define. The benefit of using FoxyProxy with Tor is simply that you can use your fast internet connection to load normal URLs and the Tor network to load sensitive URLs without constantly changing Firefox proxy settings.

  • How can I use FoxyProxy with Tor?

    Tor Browser is a customized version of Firefox. You can “side-load” FoxyProxy into the Tor Browser.

    • Download and install the Tor Browser.
    • Run it.
    • Download FoxyProxy for Firefox to your local computer. Here is the link for version 4.5.6.
    • Drag-and-drop the FoxyProxy file onto the Tor Browser. It will install and Tor Browser will prompt you to restart.
  • Miscellaneous

    • Does FoxyProxy work with Flash and Java applets?

      Yes. FoxyProxy correctly proxies Flash-, Shockwave-, and Java-initiated connections. They are routed through proxies in the same way any other connection/request is routed. Moreoever, these connections/requests are visible in the FoxyProxy Logging Tab if logging is enabled. Please note that some of these plugins may choose to ignore proxy settings and connect directly to the internet. There is no way for FoxyProxy to prevent them from doing this. The only way to make sure all the traffic is going through the proxy is to use the FoxyProxy VPN Service.

    • Does FoxyProxy work with IceWeasel?


    • Where can I get older versions of FoxyProxy?

      FoxyProxy Standard for Chrome: here
      FoxyProxy Basic for Chrome: here
      FoxyProxy Standard for Firefox: here
      FoxyProxy Basic for Firefox: here

    • Where can I find the FoxyProxy source code?

      FoxyProxy source code is available from the public Git repository located at git:// (Firefox) and git:// (Chrome). If you only want to browse the code online (or download a .zip, .tar.gz, or .tar.bz2 archive instead), consider using our Repository Viewer.

    • Firefox only. I don’t want FoxyProxy’s icon to change back to the default after page finishes loading in Use proxies based on their pre-defined patterns and priorities.

      You can disable resetting of icon colors after URLs finish loading with a “hidden preferenence” (i.e., no GUI currently). Open foxyproxy.xml and look for resetIconColors=”true”. Change true to false, and restart Firefox. This enables you to easily see which proxy was last used (instead of having to use the FoxyProxy Logging tab).
      To undo the change, change it back to true and restart Firefox.

    Video and Audio sites

    Many video sites permit their videos to be viewed only from certain countries. A common way to avoid such restrictions is to find a proxy server in the appropriate country and use FoxyProxy to load the video through that proxy server.

    In order to proxify video content without any lags and delays, the proxy you are using should be capable of high bandwidth. To obtain such a proxy in the US, UK, EU, Canada, or any other country, please order paid proxy service from us.

    Known Issues

    • Firefox only. FoxyProxy displays settings.error.3 or Error reading string resource or Error writing settings file or Error reading settings file.

      These errors almost always means FoxyProxy cannot find the file where your personal settings are saved, foxyproxy.xml. Most likely you moved or renamed your Firefox profile. FoxyProxy is looking for foxyproxy.xml in the old path, but it either no longer exists or is write-protected. You can manually change the path where FoxyProxy looks for foxyproxy.xml by opening Firefox, going to about:config, entering extensions.foxyproxy.settings in the filter box, and changing the value to a new path that exists; for example: file:///C:/foxyproxy.xml on windows or file://usr/local/home/foxyproxy.xml on linux/mac/unix. Restart Firefox and you should no longer see the error. If foxyproxy.xml is in the Firefox profile, you can tell FoxyProxy to look for it there by using the special value ” ” (a single space without the quotes). In this case, FoxyProxy won’t use any absolute paths to get foxyproxy.xml.

    • Firefox only. I moved my Firefox profile to another PC or another path. Now FoxyProxy doesn’t work. How to fix?

      You must edit the profile’s preferences. In Firefox, type about:config in the address bar. Enter extensions.foxyproxy.settings as a filter. If the preference doesn’t exist, create it as a new string (open the context menu (right-click) on any existing preference, go to the New menu, and select String). Enter extensions.foxyproxy.settings for the preference name. For the value of the string, enter the location of foxyproxy.xml in the form: file:///c:/path/to/file/foxyproxy.xml. For example: file:///C:/Documents%20and%20Settings/
      . Note that the path must be URL-encoded (e.g., space becomes %20). You can use this URL encoding calculator to easily URL encode a path. If foxyproxy.xml is in the Firefox profile, you can tell FoxyProxy to look for it there by using the special value ” ” (a single space without the quotes). In this case, FoxyProxy won’t use any absolute paths to get foxyproxy.xml.

      For Linux and Mac operating systems, exclude the drive letter; e.g. file:///home/ejung/foxyproxy.xml.

      If you are using Portable Firefox, the value of extensions.foxyproxy.settingsshould be a single space (” “). This tells FoxyProxy to look for foxyproxy.xml in the profile directory of the current drive. This is important because the drive letter of a USB drive can change.

    • Firefox only. Why does FoxyProxy sometimes use the wrong SOCKS proxy for 15 seconds?

      When using multiple SOCKS proxy servers, Firefox “remembers” the last SOCKS proxy used for a particular domain for roughly 15 seconds. For example,
      suppose you configure FoxyProxy rules such that loads through SOCKS proxy #1 and loads through proxy #2. Now you visit, forcing the resource to load through SOCKS proxy #1. A moment later you visit Unfortunately, Firefox will load through SOCKS proxy #1 instead of #2. Note that this only occurs when the domains are the same ( in this case). Waiting approximately 15 seconds makes Firefox “forget” the last SOCKS proxy used for that domain.

      This is a Firefox issue and has nothing to do with FoxyProxy. If you uninstall FoxyProxy, Firefox will exhibit the same behavior natively. FoxyProxy does, however, report on its logging tab that the correct proxies were used to load the resources, slightly confusing the issue.

      Possible workarounds:

      • Use a single SOCKS proxy. If other proxies are required, they should be HTTP proxies.
      • Wait 15 seconds before loading resources on the same domain that would normally load through different proxies.
      • Work on a Firefox patch to resolve this.

      This issue was originally confirmed on Mac OS X 10.4.11 and Windows XP SP2 with both Firefox and 3.0b2. It was originally discussed here.

    • Firefox only. I can’t talk to my HTTP proxy over port 80.

      Transparent proxies (i.e., proxies on port 80) aren’t well-supported. Use any other port besides 80. This problem was originally discussed here.

    • Firefox only. Many FoxyProxy buttons don’t have icons on my linux installation. But on Windows and OS/X, I see button icons.

      Button icons are hidden depending on the corresponding GTK setting. To change the GTK setting: gconf-editor and /desktop/gnome/interface/buttons_have_icons. This topic was originally discussed here.