Setting the Default Firefox Homepage with Autoconfig

Recently I’ve seen a lot of questions around why defaultPref in an autoconfig file doesn’t work to set the Firefox hompage. For example this:

defaultPref("browser.startup.homepage", "");

does not work.

This post should clear things up (and show you how to make it work).

So what’s unique about the browser.startup.homepage preference that it’s default values cannot be set like other preferences in the autoconfig file?

It is a complex preference.

Complex preferences are preferences whose default value is a pointer to a properties file that contains the value of the preference. Although when you go to about:config and search on browser.startup.homepage and see about:home as the value, that is not the true value of browser.startup.homepage. To see the true value, we can look in the configuration file for Firefox:

pref("browser.startup.homepage", "chrome://branding/locale/");

From there, we can look in to see the value:


So why is the browser homepage a complex preference? Complex preferences are used when you want to be able to translate a preference value. In the past, the Firefox homepage was localizable; that’s why it ended up being a complex preference.

You need to be aware of all of the complex preferences in Firefox because if you want to set the default value of any of them, you’ll need to follow the instructions I’ll give later in this post. The complex preferences you’ll probably care about are:


There are some other ones in firefox.js, but these are the important ones.

So here is the million dollar question; how do you set the default value for these preferences?

You can use a data URL to fake the complex preference behavior:

defaultPref("browser.startup.homepage", "data:text/plain,browser.startup.homepage=");

And that’s how you set the default value of the Firefox homepage with AutoConfig.

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 *

28 thoughts on “Setting the Default Firefox Homepage with Autoconfig

  1. Hello.
    I’ve tried to do what you tell in this entry of this amazing blog, but without success. Would you tell me what I’m doing wrong, please?

    I’m running Ubuntu 12.04 with Firefox 13. I’ve created the file /usr/lib/firefox/defaults/pref/hello.js with the line
    pref(“general.config.file”, “firefox.cfg”);
    and I’ve created the file /usr/lib/firefox/defaults/pref/firefox.cfg
    with the lines
    defaultPref(“browser.startup.homepage”, “data:text/plain,browser.startup.homepage=”);

    But when I start Firefox, it remains the same homepage it had before (in other words, these changes doesn’t work). I’ve tried creating a new user to see if these configurations work in a new and clean user, but it doesn’t.

    Please, please, please. What I’m doing wrong??

    Thanks, thanks, thanks!!

      • Oooh, I forgot, sorry!!!
        But I’ve added this line to /usr/lib/firefox/defaults/pref/hello.js and there’s no change. Mmmmmggghh.

        I’ve tried to update default version of Firefox in Ubuntu 12.04 to new Firefox 15, and I’ve moved my js file (hello.js) and my authconfig file (firefox.cfg) to new configuration folder /usr/lib/firefox/defaults/preferences. If I go to about:config in browser, I see that values in hello.js are correctly read, but the homepage configured in firefox.cfg still doesn’t apear.

        I’ve noticed also that default installation of Firefox in Ubuntu comes with a file called syspref.js located at /usr/lib/firefox/defaults/preferences with a commented line like defaultPref(“browser.startup.homepage”, “data:text/plain,browser.startup.homepage=”);
        but I have discomment this I doesn’t work either.

        I’ve no idea what to do now.

        Thanks for your so fast reply!!!

        • Sorry, the commented line in syspref.js file that comes in Ubuntu is
          pref(“browser.startup.homepage”, “data:text/plain,browser.startup.homepage=”);

          not defaultPref

  2. Well, two things:

    -If a put any configuration directive in my autoconfig file (firefox.cfg), it doesn’t work. It seems its a problem about locating this file, but I’ve put it in /usr/lib/firefox and in /usr/lib/firefox/defaults/preferences, …I don’t know other possible places…I’ll investigate this.

    -If a put any configuration directive in my js file (hello.js), it works perfectly. But if I try to put in this file the homepage configuration (with “pref” directive instead of “defaultPref” and with the correct format “data:text/plain…”) it doesn’t work. In fact, it’s what happens with the file “syspref.js” which is shipped by default with Ubuntu

    • Apparently defaultPref is broke in current Firefox builds and we are just now discovering it.

      lockPref should work though.

      you can test if your config file is working at all by putting errors in it and seeing if you get a popup.

      • Thanks.
        I don’t know why, but neither /usr/lib/firefox/firefox.cfg nor /usr/lib/firefox/defaults/preferences/firefox.cfg are found. I wish “general.config.file” could admit paths…

        Other thing: lockPref works perfectly inside a my js file (hello.js). However, not only defaultPref doesn’t work (as you say), but pref doesn’t work neither.

        Thanks a lot

        • I point out…lockPref works well with syntax:
          Syntax with “data:text/plain…” stuff isn’t recognized.
          I suppose you knew perfectly, but just in case…

  3. I have been using file to set browser.startup.homepage and browser.startup.homepage_reset but that does not seem to be working any more (Firefox 10.0.9ESR). Should I move to the method described above? Is not supported anymore?

    • only has one line in it now:


      So it’s only used for the homepage (not reset).

      browser.startup.homepage_reset is not used at all anymore.

  4. Dear Mike,
    I have been looking for many hours on how to set the homepage as a _default_ that a user can change and not have it forced as an effective policy. Many blog entries and forum participants I’ve tripped over on my search have been flummoxed by this, but you’ve explained it simply and with authority.

    So: Thank you!

    Kind regards,
    Darren Collins
    IT Services
    University of Oxford

  5. For the record, I had to set also
    in my autoconfig.js file for this to work, if I not set it, I can use pref or lockPref, but not defaultPref for browser.startup.homepage

  6. I don’t usually respond to blog posts, certainly not blog posts that are “old”.

    I really can’t get this to work, and I don’t know what to try anymore. Autoconfig works great, the pref for the default homepage works, but somehow I can’t get this to work.
    I’m stumped! Starting firefox with a batchfile so it writes information to a logfile isn’t also helping me any further.

    This is part of my autoconfig file:
    try {

    gceSystem = getenv(“GCE”);

    // Default homepage
    if(gceSystem = “1”) {
    pref(“browser.startup.homepage”, “”);
    } else {
    defaultPref(“browser.startup.homepage”, “data:text/plain,browser.startup.homepage=”);

    } catch(e) {
    displayError(“firefox_global_settings.js”, e);

    Maybe you can help? I’m left to aimlessly trying options to find out what works 🙁
    (system variable GCE is set to 0 or 1, depending on the type of system: business or home)

      • Thanks for responding!

        I’m not seeing any error, the default homepage is just the site, when that GCE system variable is set to 0. It’s just as if the script does not reach the ‘else’ part.
        I have noticed when you make an error in the autoconfig file that firefox doesn’t pick up on any changes, and maybe uses the failover.jsc file in the profile directory. This makes it a bit harder to troubleshoot (However, in this case the contents of the failover.jsc file are the same as the autoconfig file.)

        The only thing yet to try is to make a separate autoconfig file for my home users. I just don’t _get_ it. I have verified with an other variable that the if-else structure I’m using works. Maybe it works with a plain autoconfig file for home use, but what would cause that kind of behaviour – as said, I’m stumped!

        I would use CCK2, if it were not that I have more flexibility now with my package manager. I also have a lot of problems with getting extensions to enable for a new user, but this is an entirely different problem, and something I can spend more time on before asking for help.
        The default homepage thing is now just getting beyond my reach. I’m going to test a few things so I hope I can provide some more information on what exactly doesn’t work.

        • Well, I finally figured it out:
          the if statement needs to be with == instead of =
          I thought I had tested that..! (argh!)

          Now it’s like this:
          try {

          gceSystem = getenv(“GCE”);

          // Default homepage
          if(gceSystem == “1”) {
          pref(“browser.startup.homepage”, “”);
          pref(“”, 3);
          } else {
          defaultPref(“browser.startup.homepage”, “data:text/plain,browser.startup.homepage=”);
          defaultPref(“”, 3);

          } catch(e) {
          displayError(“firefox_home_settings.js”, e);

  7. Amazing how poorly documented this is. I’ve been looking at the official Mozilla documents, and no mention is made of this issue. Thanks for taking the time to share the knowledge on this.

  8. Thanks for the solution. This works great for the local administrator. But when a domain user logs in it does not set to the homepage that we specify in the Mozilla.cfg. how can we apply this to all user who log in to the system?

    • I’m not sure how that would be possible. The Autoconfig is used anytime the executable is started (it’s not user specific). What homepage are they seeing?

  9. I’m not sure exactly when this changed, but I tried just entering it in like you would expect and it worked without issue (Firefox 46.0). No fanciness required. In my mozilla.config file all I have is lockPref(“browser.startup.homepage”, “URL”); and that works.

      • Can anyone help me?
        Deploying via SCCM with mozilla.cfg, local-settings.js, overide.ini and an install.cmd that calls FF46 to install and then copies those three files over correctly. Works great except I have discovered that when I set the home page in the mozilla.cfg users are unable to change after the fact. It always resets to the one I have in the cfg file. Which personally is fine by me but now people are complaining they can’t change it.