Creating a Customized Firefox Distribution

You may have heard of the the Firefox Build Your Own Browser Project. On the web page, it says it “is a simple way that your organization can create and distribute a customized version of Firefox.” I think BYOB is a great start to solving the distribution problem, but it’s missing one key thing – the ability to bundle your own add-ons.

What I’m going to do with this post is explain exactly how BYOB works internally so that you can create your own distribution that has all the customizations you want. There are a some downsides to our method – primarily that we are Windows only and that we can’t sign our installers with the Mozilla certificate. But it’s the only way we can create a distribution that includes our own add-ons.

BYOB works by taking advantage of the features of the distribution directory in Firefox. The main component of the distribution directory is the distribution.ini file. The distribution.ini does have some documentation, but there are a few more tricks that we need to know about.

Previously I had talked about customizing the Firefox installer, and all that information is going to come into play here. What we’re going to do is after we’ve unpacked the Firefox installer we want to use, we’re going to create a subdirectory called distribution in the nonlocalized directory. In that directory, we’re going to create a file called distribution.ini. We can use this web page as a template for that file. The distribution.ini file is going to contain any preferences and bookmarks that we want to specify as part of our distribution. Information on how to create those things is in the sample file.

Next up are search engines. Search engines are placed in a subdirectory called searchplugins under the distribution directory. For search engines that we want installed for everyone, we put them in another subdirectory called common (searchplugins/common). If there are search plugins we want to be locale specific, we can put them in a directory that is named the same as the locale (This is all documented in the sample distribution.ini).

When I talked about customizing the Firefox installer, I indicated that you could preinstall add-ons by unzipping them into the nonlocalized/extensions directory. With the distribution directory, we have a new option. If we create a bundles directory and then put our add-ons in there, they are completely hidden from the user. They can’t be uninstalled or disabled. The method for putting add-ons in this directory is the same as before – create a directory that named the same as the ID of the add-on and then unzip the add-on into that directory.

If you’ve used BYOB, though, you may have noticed that they do things a little differently. If you bundle add-ons with your browser, they are installed the first time you start the browser. And if you create another profile, it gets those add-ons as well. And they are installed into your profile directory. This is accomplished is via a custom add-on that was created by Appcoast called the Addon Installer. I could find no information at all on this add-on. I’m going to document here how it works, but if you choose to use it, it’s at your own risk. To obtain it, you can download any of the browsers at the bottom of the BYOB page. After unpacking one of those installers, you’ll see the Addon Installer in nonlocalized/distribution/bundles/{04C927C9-E491-4DDC-9D45-54C145422A15}. Just duplicate that directory in your distribution. If I get a chance, I might create a version of this that is open source.

To use the Addon Installer, place the XPI files you want to install into a directory called extensions under the distribution directory. Then create a file called config.ini in that directory. The format of the config.ini file is like this:


Most of this is self explanatory. The only interesting part is OS. If for some reason, you need an add-on to be OS specific, put the OS name instead of ALL. You can see the OS names here.

Once we’ve made all these customizations, we can follow the instructions in my previous post to package our installer. Also, if you want your installer to say “Mozilla Firefox for Your Company”, don’t forget that you can do that using the setup.ini that is mentioned in that previous post. That’s in localized/distribution, NOT nonlocalized/distribution.

So in summary, while I usually plug the CCK Wizard, if all you need to do is set some default prefs, add some bookmarks, bundle some search engines and bundle some add-ons, the distribution method might be for you. If you need to do more detailed customizations, check out the CCK Wizard.

And as always, if you need help with any of this, you can contact Kaply Consulting.

Please note: I reserve the right to delete comments that are offensive or off-topic.

Leave a Reply

Your email address will not be published. Required fields are marked *

20 thoughts on “Creating a Customized Firefox Distribution

  1. @Robert Kaiser

    > You imply that BYOB builds are not completely open-source?

    All of the source files for the Addon Installer have “Copyright (c) 2010 Appcoast Ltd. All rights reserved” at the top except for moz4log.js which came from here

    So these files are definitely NOT open source.

  2. With regards to the licensing of the add-on installer extension, this was an oversight on my part. They will be licensed under the MPL, and I’ll get that change in place by the end of the week.


  3. Firstly thanks for a great article. I however have a couple of questions that you may be able to answer.
    I am trying to come up with a default coporate interface for Firefox, remove all toolbars, add a site certificate in, setup default homepage etc. As part of these customisations I have installed a couple of extensions eg Menu Editor which allows me to remove specific/all entries on the menu. I do all of my customisation and get the interface looking just as I want it. I then copy my entire profile folder – located here:
    to the expanded Firefox installation source files:

    If I then run an install using these modified source files, I get a default Firefox configuration as I intend, unfortunately the configuration that I did via the extensions does not works. The extensions do appear within the addons page but I cannot even configure them manually.

    How do I combine my Firefox customisations with successfully entension deployment & configuration?

    Many thanks!

  4. I’m trying to customize a Firefox (10esr) for MAC. I’m using CCK to create the extension but I can’t find the correct path to extract it, in order to have the extension installed for all users.

    I’m extracting it on “” but the extension only get installed on new users profile. Where should I extract it to make it available to every user, not just new profiles?


      • Hey Mike!

        Thanks for the quick reply!

        Tried “”, but had no luck. Extension do not get installed. Did mozilla change the paths on mac?

        • Did you use bundle or bundles?

          Basically you create a directory underneath distribution/bundles and unzip your add-on into that directory (it doesn’t matter what the directory is named). Like:


          Note that when you do this, the add-on won’t show up in the add-ons manager at all, but the functionality will be there.

          • It was my mistake! I was using “bundle” instead of “bundles”. Now it is available to all profiles, not just new ones.

            But now the extension is hidden from final user. Is there a way to make it available to every profile available and make it visible as well?

            Extracting to “” would make it visible to user, but would only be installed on new profiles. Current profile would not get the extension.

  5. I’m having a problem with bundled extensions of the \distribution directory

    bootstrapped addons like Adblock Plus simply wont load. may you can find out why


    • Unfortunately because bootstrapped add-ons don’t use chrome.manifest for loading, they don’t work in distribution/bundles. This post has a little more information.

  6. Excellent post. I was checking constantly this weblog and I’m impressed!

    Extremely useful information particularly the closing phase 🙂 I maintain such
    information a lot. I was looking for tis particular information for a long
    time. Thank you and best of luck.

    • I created a silent install. I would like to find out how I can add to the PersonalToolbar the print-button during the silent install.
      I working in Win7 with Firefox 56.0.1.

      Thank you,