User.js file: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
m (replace wrongtitle with Profile file template)
(→‎External links: updated links, reordered; added link to Bug 557738 - Add user.js section to about:support)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{profile-file|filename=user.js}}
{{profile-file|filename=user.js}}


The ''user.js'' file, located in the [[profile folder]], is used to customize preference settings in Mozilla-based programs. When you launch the application, the valid preferences you've added to user.js are then automatically copied into the [[prefs.js file]] (also located in the same profile folder), which stores all the preferences for the current user. For that reason, before you create or edit the user.js file it is advisable to make a backup copy of the prefs.js file.  Although the prefs.js file can be modified using ([[about:config]]) or through the options and preference settings within the Firefox/Thunderbird/Mozilla Suite program's user-interface, the preferences you add via the ''user.js'' file will '''never''' be modified unless you yourself edit the user.js file contents.
A ''user.js'' file is an alternative method of [[Editing_configuration#Modifying_preferences |modifying preferences]], recommended for advanced users only. Unless you need a user.js file for a specific purpose you should use [[about:config]] instead.   The user.js file does not exist by default.  


== Creating the user.js file==
'''Important: ''' Once an entry for a preference setting exists in the user.js file, any change you make to that setting in the options and preference dialogs or via [[about:config]] will be lost when you restart your Mozilla application because the user.js entry will override it.
The user.js file does not exist by default, and so you'll need to create the file before you can start adding your preferences. Either use the [https://addons.mozilla.org/extensions/moreinfo.php?id=17 ChromEdit] extension, or open Notepad or another text editor, type in the preference entries (and any comments) then save the file as "user.js" inside your [[profile folder]].  (On Windows OS,  make sure you UNhide extensions for known filetypes in Folder Options, so that the file isn't really called "user.js.txt".) 


Valid preferences are entered via the user_pref command, as demonstrated below.   '''//'''  denotes a comment, so anything after these two characters on a line is ignored. A valid preference entry always begins with ''user_pref'' and always ends with a semi-colon;  every preference must be entered on a new lineIn Windows, if the preference value specifies a folder path, the path separator must be two backslashes.
==About the user.js file==
A user.js file can make certain preference settings more or less "permanent" in a specific profile, since you'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the applicationThis has the advantage of locking in certain preference settings.  A user.js file is also a way of documenting preference customizations and it makes it easier to transfer customized settings to another profile.


// relocate parent directory for browser cache
When you launch your Mozilla application, valid preferences you've added to the user.js file are automatically copied to the [[prefs.js file]] (located in the same [[profile folder]]) where all user-set preferences are stored.  For this reason, you should make a backup copy of the prefs.js file before you create or edit the user.js file.  
user_pref("browser.cache.disk.parent_directory", "D:\\Mozilla\\Firefox\\");
// relocate or share the browser bookmarks file
user_pref("browser.bookmarks.file", "D:\\Mozilla\\Firefox\\bookmarks.html");
   
For a list of valid preferences, consult the [[about:config entries]] article.


==Changing user.js entries ==
==Creating the user.js file==
To edit user.js, either use the [https://addons.mozilla.org/extensions/moreinfo.php?id=17 ChromEdit] extension, or open the file in a text editor such as Notepad, make your changes, then close the file and save the changes.  
To create a user.js file, open a text editor such as Notepad and save the empty file as "user.js" inside your [[profile folder]]. (If you use a Windows text editor, make sure you unhide extensions for known filetypes in Folder Options, so that the file isn't really called "user.js.txt". See also the [[Editing configuration/Manual editing | manual editing advice]].)


To undo preferences that have been set in the ''user.js'' file:
==Adding user.js entries==
# Remove the unwanted preference entries fom the user.js file as a first step.  However, since the same preference is now written to the  [[prefs.js file]], a second step is needed:
To add preferences to user.js, open the file in a text editor such as Notepad, and type in the preference entries (and any comments) as follows. (After adding the entries, you must save the file! Changes will not take effect until you restart your Mozilla application.)
# Also remove the preference entries from ''prefs.js'', either by direct editing of the prefs.js file (not recommended) or by resetting the preference via [[about:config]].
 
Valid preferences are entered via the user_pref command, as demonstrated below.  <code>//</code> denotes a comment, so anything after these two characters on a line is ignored.  A valid preference entry always begins with ''user_pref'' and always ends with a semi-colon;  every preference must be entered on a new line. A preference consists of a &lsquo;name&rsquo; (such as '''browser.chrome.site_icons''') and a &lsquo;value&rsquo;.  A value may either be integer ('''0''', '''2''' etc.), boolean ('''true''' or '''false''') or string (text, such as a file path).  For example, you could add the following lines to your user.js file if you wished to disable bookmark icons:
 
// Don't show bookmark icons
user_pref("browser.chrome.site_icons", false);
 
Many Knowledge Base articles discuss individual preferences and their values. For a comprehensive list of valid preferences and their values, consult the [[about:config entries]] article.
 
Note that in Windows, if the preference value is a folder path then the path separator must be two backslashes. For example,
 
// Relocate parent directory for browser cache
user_pref("browser.cache.disk.parent_directory", "D:\\Mozilla\\Firefox\\");
 
==Editing user.js entries ==
To edit the user.js file, open the file in a text editor such as Notepad, make your changes, then close the file and save the changes.  Note that removing or "commenting out" a preference line from the user.js file will not remove changes written to the [[prefs.js file]] (see below).
 
==Removing user.js entries==
To undo preferences that have been set in the user.js file:
# Edit the user.js file to remove the unwanted preference entries or delete the user.js file to remove all entries, as a first step.  Since the same preferences are now written to the  [[prefs.js file]], a second step is needed:
# If there are no options in the user interface (UI) for the preference, either directly edit the prefs.js file to remove the unwanted entries (not recommended), reset the preference via [[about:config]] or restore a backup copy of the [[prefs.js file]].
 
==See also==
*[[Resetting preferences]]
*[[Editing configuration]]


==External links==
==External links==
* [http://www.mozilla.org/support/firefox/edit Firefox Help: Editing Configuration Files]  
* [http://ilias.ca/archive/userjs How to Create and Use the user.js in Windows] (ilias.ca)
* [http://www.mozilla.org/catalog/end-user/customizing/briefprefs.html A Brief Guide to Mozilla Preferences]
* [http://webdesigns.ms11.net/chromeditp.html ChromEdit Plus] This extension provides a convenient way of editing user.js and other Mozilla configuration files
* [http://ilias.ca/userjs.html How to Create and Use the USER.JS in Windows]
* [https://developer.mozilla.org/en-US/docs/Code_snippets/Preferences Preferences - MDN]
* [https://developer.mozilla.org/en-US/docs/Thunderbird/Thunderbird_Configuration_Files Thunderbird Configuration Files - MDN]
* [http://www-archive.mozilla.org/catalog/end-user/customizing/briefprefs.html A Brief Guide to Mozilla Preferences]
* [https://bugzilla.mozilla.org/show_bug.cgi?id=557738 Bug 557738 - Add user.js section to about:support]  
 


[[Category:Configuration]]
[[Category:Configuration]]
[[Category:Configuration (Thunderbird)]]
[[Category:Configuration (Thunderbird)]]

Latest revision as of 15:17, 11 October 2012

A user.js file is an alternative method of modifying preferences, recommended for advanced users only. Unless you need a user.js file for a specific purpose you should use about:config instead. The user.js file does not exist by default.

Important: Once an entry for a preference setting exists in the user.js file, any change you make to that setting in the options and preference dialogs or via about:config will be lost when you restart your Mozilla application because the user.js entry will override it.

About the user.js file

A user.js file can make certain preference settings more or less "permanent" in a specific profile, since you'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the application. This has the advantage of locking in certain preference settings. A user.js file is also a way of documenting preference customizations and it makes it easier to transfer customized settings to another profile.

When you launch your Mozilla application, valid preferences you've added to the user.js file are automatically copied to the prefs.js file (located in the same profile folder) where all user-set preferences are stored. For this reason, you should make a backup copy of the prefs.js file before you create or edit the user.js file.

Creating the user.js file

To create a user.js file, open a text editor such as Notepad and save the empty file as "user.js" inside your profile folder. (If you use a Windows text editor, make sure you unhide extensions for known filetypes in Folder Options, so that the file isn't really called "user.js.txt". See also the manual editing advice.)

Adding user.js entries

To add preferences to user.js, open the file in a text editor such as Notepad, and type in the preference entries (and any comments) as follows. (After adding the entries, you must save the file! Changes will not take effect until you restart your Mozilla application.)

Valid preferences are entered via the user_pref command, as demonstrated below. // denotes a comment, so anything after these two characters on a line is ignored. A valid preference entry always begins with user_pref and always ends with a semi-colon; every preference must be entered on a new line. A preference consists of a ‘name’ (such as browser.chrome.site_icons) and a ‘value’. A value may either be integer (0, 2 etc.), boolean (true or false) or string (text, such as a file path). For example, you could add the following lines to your user.js file if you wished to disable bookmark icons:

// Don't show bookmark icons
user_pref("browser.chrome.site_icons", false);

Many Knowledge Base articles discuss individual preferences and their values. For a comprehensive list of valid preferences and their values, consult the about:config entries article.

Note that in Windows, if the preference value is a folder path then the path separator must be two backslashes. For example,

// Relocate parent directory for browser cache
user_pref("browser.cache.disk.parent_directory", "D:\\Mozilla\\Firefox\\");

Editing user.js entries

To edit the user.js file, open the file in a text editor such as Notepad, make your changes, then close the file and save the changes. Note that removing or "commenting out" a preference line from the user.js file will not remove changes written to the prefs.js file (see below).

Removing user.js entries

To undo preferences that have been set in the user.js file:

  1. Edit the user.js file to remove the unwanted preference entries or delete the user.js file to remove all entries, as a first step. Since the same preferences are now written to the prefs.js file, a second step is needed:
  2. If there are no options in the user interface (UI) for the preference, either directly edit the prefs.js file to remove the unwanted entries (not recommended), reset the preference via about:config or restore a backup copy of the prefs.js file.

See also

External links