Difference between revisions of "Configuration Locations"

From GnuCash
Jump to: navigation, search
(HOME: minor stylistic edit)
(File environment.local - Fix Windows path)
(19 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
=Introduction=
 +
GnuCash stores several categories of information regarding your setup in several locations on your machine. In addition to your financial data file itself, there are configuration settings that control how your copy of GnuCash looks and acts, and there are custom report settings.
 +
 +
''This page focuses on the files and locations of configuration settings under the different operating systems that GnuCash supports.''
 +
 +
:;Important Note: '''Your Financial data file(s) are not located in any pre-specified location. They are located wherever you have chosen to place them on your system.'''
 +
 
GnuCash will read several configuration files in different directories. And several pages on this wiki will refer to one or more of these. As these directories often differ between operating systems and may be overridden in several ways, this page will attempt to give an overview. What each file does can be found on other pages instead.
 
GnuCash will read several configuration files in different directories. And several pages on this wiki will refer to one or more of these. As these directories often differ between operating systems and may be overridden in several ways, this page will attempt to give an overview. What each file does can be found on other pages instead.
  
;A note beforehand on operating systems: This page will frequently mention different operating systems. However to keep the text manageable it won't list all systems on which GnuCash is known to run, unless it's important for differentiation. In general the page will mention
+
'''Note:''' Unless described more specifically, the following general operating systems definitions will be used:
:;Linux: which also includes many similar operating systems that adhere to the Free Desktop specification like various '''BSD''' flavours,
 
:;Windows: for all supported Windows versions or
 
:;MacOS (formerly OS X): for the version of GnuCash that is built with ''Quartz'' integration, like the bundle that can be downloaded on the GnuCash website. On MacOS there is also a '''MacPorts''' version of GnuCash. Except for the MacOS proper home directory it behaves identical to Linux and variants. So it will only be listed in the HOME directory definition.
 
  
== Directories ==
+
:;Linux: including many similar operating systems that adhere to the Free Desktop specification like various '''BSD''' flavors,
 +
:;Windows: for all supported Windows versions
 +
:;MacOS (formerly OS X): for the version of GnuCash that is built with ''Quartz'' integration, and can be downloaded from the GnuCash website. On MacOS there is also a '''MacPorts''' version of GnuCash. Except for the MacOS proper home directory it behaves identical to Linux and variants. So it will only be listed in the HOME directory definition.
 +
 
 +
=Directories=
  
 
Let's start with defining a few common directory locations that will be referred to regularly.
 
Let's start with defining a few common directory locations that will be referred to regularly.
  
=== HOME ===
+
== HOME ==
 
The user's home directory on your computer. While this may be obvious, it is mentioned here because it's the base directory for several others below. The usual locations per OS are:
 
The user's home directory on your computer. While this may be obvious, it is mentioned here because it's the base directory for several others below. The usual locations per OS are:
  
 
;Linux: <tt>/home/<username></tt> - for example ''/home/johndoe''
 
;Linux: <tt>/home/<username></tt> - for example ''/home/johndoe''
:Note that in a linux context this directory is also often referred to as <tt>$HOME</tt> or <tt>~/</tt>
+
:Note that this directory is also often referred to as <tt>$HOME</tt> or <tt>~/</tt>
 
;Windows 7 and more recent: <tt>c:\Users\<username></tt> - for example ''c:\Users\johndoe''
 
;Windows 7 and more recent: <tt>c:\Users\<username></tt> - for example ''c:\Users\johndoe''
 
;Windows Vista and older: <tt>c:\Documents and settings\<username></tt> - for example ''c:\Documents and settings\johndoe''
 
;Windows Vista and older: <tt>c:\Documents and settings\<username></tt> - for example ''c:\Documents and settings\johndoe''
Line 21: Line 29:
 
In the following directories, this base directory will be referred to as ''HOME''.
 
In the following directories, this base directory will be referred to as ''HOME''.
  
=== USER_DATA_HOME ===
+
== USER_DATA_HOME ==
 
This directory can be used by applications to store data that can't be stored in the user's data file for some reason. For example gnucash will store saved reports here, or some metadata such as which register tabs were open for your books last time you closed them. The default locations:
 
This directory can be used by applications to store data that can't be stored in the user's data file for some reason. For example gnucash will store saved reports here, or some metadata such as which register tabs were open for your books last time you closed them. The default locations:
  
Line 33: Line 41:
 
:<tt>HOME/Library/Application Support</tt> (or <tt>HOME/Library/Applications Defaults for OS X 10.6 and older</tt>)
 
:<tt>HOME/Library/Application Support</tt> (or <tt>HOME/Library/Applications Defaults for OS X 10.6 and older</tt>)
 
:<tt>HOME/.local/share</tt>
 
:<tt>HOME/.local/share</tt>
:The former is native to MacOS (and will be used by GnuCash), the latter is often used by software that's ported from linux (like Gtk3). The difference will get clearer further down.
+
:The former is native to MacOS (and will be used by GnuCash), the latter is often used by software that's ported from linux (like GTK3). The difference will get clearer further down.
  
It's important to understand this directory is shared by all applications you run on your system. So aside from gnucash, applications like Firefox, Microsoft Office, LibreOffice and so on will also write here. To avoid clutter most applications have the courtesy to create their own subdirectory in here and only write in that subdirectory. This leads us seamlessly to the next couple of important directories:
+
It's important to understand this directory is shared by all applications you run on your system. So aside from GnuCash, applications like Firefox, Microsoft Office, LibreOffice and so on will also write here. To avoid clutter, most applications have the courtesy to create their own subdirectory here and only write in that subdirectory. This leads seamlessly to the next couple of important directories:
  
=== GNC_DATA_HOME ===
+
== GNC_DATA_HOME ==
 
'''Versions:''' 3.x and more recent
 
'''Versions:''' 3.x and more recent
  
This is the subdirectory in USER_DATA_HOME GnuCash uses exclusively for it's user specific data. The default locations:
+
This is the subdirectory in USER_DATA_HOME that GnuCash uses exclusively for its user specific data. The default locations:
  
 
;Linux: <tt>USER_DATA_HOME/gnucash</tt>
 
;Linux: <tt>USER_DATA_HOME/gnucash</tt>
Line 46: Line 54:
 
;MacOS: <tt>HOME/Library/Application Support/GnuCash</tt>
 
;MacOS: <tt>HOME/Library/Application Support/GnuCash</tt>
  
To note is that on Windows the base directory is ''APPDATA'' and on OS X this is ''HOME/Library/Application Support''. The base directories will be different for the next relevant directory:
+
Note that on Windows the base directory is ''APPDATA'' and on MacOS this is ''HOME/Library/Application Support''. The base directories will be different for the next relevant directory:
 +
 
 +
== GTK_DATA_HOME ==
 +
 
 +
'''Versions:''' 3.x and more recent
  
=== GTK_DATA_HOME ===
+
GnuCash uses GTK for its graphical user interface; thus, locations that are used by GTK are also relevant. Note the base directories on Windows and MacOS for this differ from the base directories for GNC_DATA_HOME.
As gnucash is using Gtk for its graphical user interface, locations that are used by Gtk are also relevant. Note the base directories on Windows and MacOS for this one differ from the base directories for GNC_DATA_HOME.
 
  
 
;Linux: <tt>USER_DATA_HOME/gtk-3.0</tt>
 
;Linux: <tt>USER_DATA_HOME/gtk-3.0</tt>
Line 55: Line 66:
 
;MacOS: <tt>HOME/.local/share/gtk-3.0</tt>
 
;MacOS: <tt>HOME/.local/share/gtk-3.0</tt>
  
=== USER_CONFIG_HOME ===
+
== USER_CONFIG_HOME ==
This directory is used to configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows for example there is no difference between the two and USER_DATA_HOME will be used. On linux GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). I believe Gtk3 maintains a similar strategy. On MacOS it's a bit more complicated as GnuCash will use USER_DATA_HOME for all GnuCash own configuration files, but another directory for all of its support libraries.
+
This directory is used for configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows, for example, there is no difference between the two and USER_DATA_HOME will be used. On Linux, GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). GTK3 seems to maintain a similar strategy. On MacOS, it's a bit more complicated; GnuCash will use USER_DATA_HOME for all its own configuration files, but another directory for all of its support libraries.
  
 
Default locations:
 
Default locations:
 
;Linux: <tt>HOME/.config</tt>
 
;Linux: <tt>HOME/.config</tt>
;Windows: On this platform there are actually two directories for this kind of data:
+
;Windows: There are two directories for this kind of data:
 
:<tt>HOME\AppData\Local</tt>, often referred to as %LOCALAPPDATA%
 
:<tt>HOME\AppData\Local</tt>, often referred to as %LOCALAPPDATA%
 
:<tt>HOME\AppData\Roaming</tt>, often referred to as %APPDATA%
 
:<tt>HOME\AppData\Roaming</tt>, often referred to as %APPDATA%
 
:The reason for having two is not important in the scope of this page.
 
:The reason for having two is not important in the scope of this page.
 
:'''Note''' %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
 
:'''Note''' %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
;MacOS: On this platform there are actually two directories for this kind of data:
+
;MacOS: There are two directories for this kind of data:
 
:<tt>HOME/Library/Application Support</tt>
 
:<tt>HOME/Library/Application Support</tt>
 
:<tt>HOME/Library/Application Support/config</tt>
 
:<tt>HOME/Library/Application Support/config</tt>
:The former is native to MacOS (and will be used by GnuCash), the latter is what GnuCash configures for all its support libraries (like Gtk3).
+
:The former is native to MacOS (and will be used by GnuCash), the latter is what GnuCash configures for all its support libraries (like GTK3).
  
 
Like USER_DATA_HOME USER_CONFIG_HOME is common for all applications. Each application will typically expect an application specific subdirectory here.
 
Like USER_DATA_HOME USER_CONFIG_HOME is common for all applications. Each application will typically expect an application specific subdirectory here.
  
=== GNC_CONFIG_HOME ===
+
== GNC_CONFIG_HOME ==
 
'''Versions:''' 3.x and more recent
 
'''Versions:''' 3.x and more recent
  
This is the subdirectory in USER_CONFIG_HOME GnuCash uses exclusively for it's user specific configuration data. The default locations:
+
This is the subdirectory in USER_CONFIG_HOME GnuCash uses exclusively for its user specific configuration data. The default locations:
  
 
;Linux: <tt>USER_CONFIG_HOME/gnucash</tt>
 
;Linux: <tt>USER_CONFIG_HOME/gnucash</tt>
Line 81: Line 92:
 
;MacOS: <tt>HOME/Library/Application Support/GnuCash</tt>
 
;MacOS: <tt>HOME/Library/Application Support/GnuCash</tt>
  
To note is that on Windows the base directory is ''APPDATA'' and on OS X this is ''HOME/Library/Application Support''. The base directories will be different for the next relevant directory:
+
Note that on Windows, the base directory is ''APPDATA'' and on MacOS, this is ''HOME/Library/Application Support''. The base directories will be different for the next relevant directory:
  
=== GTK_CONFIG_HOME ===
+
== GTK_CONFIG_HOME ==
As gnucash is using Gtk for its graphical user interface, locations that are used by Gtk are also relevant. Note the base directories on Windows and MacOS for this one differ from the base directories for GNC_DATA_HOME.
 
  
;Linux: <tt>USER_CONFIG_HOME/gtk-3.0</tt>
+
GnuCash uses GTK for its graphical user interface; thus, locations that are used by GTK are also relevant. The folders differ by GnuCash version.
;Windows: <tt>%LOCALAPPDATA%\gtk-3.0</tt>
+
 
;MacOS: <tt>HOME/Library/Application Support/GnuCash/gtk-3.0</tt>
+
*For GnuCash 2.6.x and older, GTK uses the HOME directory for resource files.
 +
 
 +
*For GnuCash 3.0 and later. Note the base directories on Windows and MacOS for this differ from the base directories for GNC_DATA_HOME.
 +
:;Linux: <tt>USER_CONFIG_HOME/gtk-3.0</tt>
 +
:;Windows: <tt>%LOCALAPPDATA%\gtk-3.0</tt>
 +
:;MacOS: <tt>HOME/Library/Application Support/GnuCash/config/gtk-3.0</tt>
  
=== DOT_GNUCASH_DIR  ===
+
== DOT_GNUCASH_DIR  ==
 
'''Versions:''' 2.6.x and older
 
'''Versions:''' 2.6.x and older
  
GnuCash 2.6 and older didn't make the distinction between [[#GNC_DATA_HOME]] and [[#GNC_CONFIG_HOME]]. Instead these versions of gnucash stored the same (meta)data and configuration files in this single directory instead. The default locations:
+
GnuCash 2.6 and older don't distinguish between [[#GNC_DATA_HOME]] and [[#GNC_CONFIG_HOME]]. Instead, these versions of GnuCash store both metadata and configuration files in a single directory. The default locations are:
  
 
;Linux: <tt>HOME/.gnucash</tt>
 
;Linux: <tt>HOME/.gnucash</tt>
Line 99: Line 114:
 
;MacOS: <tt>HOME/Library/Application Support/Gnucash</tt>
 
;MacOS: <tt>HOME/Library/Application Support/Gnucash</tt>
  
For GnuCash 3.0 and up these files were moved into different locations to better integrate with each supported platform's recommended locations. When moving from GnuCash 2.6 to 3.x or above GnuCash will automatically try to migrate all data from DOT_GNUCASH_DIR to their respective new locations. After that GnuCash 3.x or above will never use DOT_GNUCASH_DIR again.
+
For GnuCash 3.0 and up, these files have been moved to different locations to integrate better with each supported platform's recommended locations. When moving from GnuCash 2.6 to 3.x or above, GnuCash will automatically try to migrate all data from DOT_GNUCASH_DIR to their respective new locations. After mitgration, GnuCash 3.0 or above should never use DOT_GNUCASH_DIR again.
  
== Files ==
+
= Files =
  
With the most common base directories defined we can now create a reference list of relevant data and configuration files in each of these directories.
+
With the most common base directories defined, we can now create a reference list of relevant data and configuration files in each of these directories.
  
=== In GNC_DATA_HOME ===
+
== In GNC_DATA_HOME ==
  
As written above GnuCash manages these files for you. So usually there's no need to manipulate these by hand. If you do need to make changes be sure to do so while GnuCash is not running.
+
As noted, GnuCash manages these files for you. So usually there's no need to manipulate these by hand. If you do need to make changes be sure to do so while GnuCash is not running.
  
 
;accelerator-map: A file in which custom accelerator key bindings are stored.
 
;accelerator-map: A file in which custom accelerator key bindings are stored.
;books/<name>.gcm: GnuCash tracks all metadata related to a book in this file. There will be one such file for each book you have ever created/opened. This metadata contains things like window positions, sort orders, which columns to show, CSV import presets,...
+
;books/<name>.gcm: GnuCash tracks all metadata related to a book in this file. There will usually be one such file for each book you have ever created/opened. This metadata includes things like window positions, sort orders, which columns to show, CSV import presets,... See [[Metadata_File]] for more details.
;checks: a directory to hold custom check formats.
+
;checks: A directory to hold custom check formats.
 
:''Note for developers:'' this should probably live in GNC_CONFIG_HOME as this is mostly user configurable data.
 
:''Note for developers:'' this should probably live in GNC_CONFIG_HOME as this is mostly user configurable data.
;expressions-2.0: a file to contain custom expressions managed by the GnuCash expression parser.
+
;expressions-2.0: A file to contain custom expressions managed by the GnuCash expression parser.
 
:''Note for developers:'' This file needs more documentation.
 
:''Note for developers:'' This file needs more documentation.
;qif-accounts-map: used by the qif importer to keep track of mappings between qif account references and gnucash accounts. This file is formatted in the guile scripting language.
+
;qif-accounts-map: Used by the qif importer to keep track of mappings between qif account references and gnucash accounts. This file is formatted in the guile scripting language.
;saved-reports-x.y: this file keeps track of all saved report configurations you have created in gnucash. There may be more than one such file with different numbers in x.y. Normally the highest number is the active file while those with lower numbers are kept as a backup (they were the main file for older versions of gnucash). As qif-accounts-map this file is formatted in the guile scripting language.
+
;saved-reports-x.y: This file keeps track of all saved report configurations you have created in gnucash. There may be more than one such file with different numbers in x.y. Normally the highest number is the active file while those with lower numbers are kept as a backup (they were the main file for older versions of gnucash). As qif-accounts-map this file is formatted in the guile scripting language.
;stylesheets-2.0: this file keeps track of all personalized style sheets for reports. This file is formatted in the guile scripting language as well.
+
;stylesheets-2.0: This file keeps track of all personalized style sheets for reports. This file is formatted in the guile scripting language as well.
  
=== In GTK_CONFIG_HOME ===
+
== In GTK_CONFIG_HOME ==
 +
;For GnuCash version 3.0 and later:
 +
:;settings.ini: a configuration file in which several aspects of GTK3 can be configured. Examples are the theme, the default font and size, scrollbar behaviour, ...
 +
::The full list of configurable parameters can be found on the [https://developer.gnome.org/gtk3/stable/GtkSettings.html GTK Settings page]
 +
:;gtk.css: a [[CSS]] file for styling GTK widgets. Any css changes in this file will override overlapping style information in the current theme so this can be used to tweak the theme in more detail.
 +
:;gtk-3.0.css: a second css file that will take precedence over the information in gtk.css.
 +
:More information on how these file are used can be found at the [[GTK3]] page. That page has several examples as well.
  
;settings.ini: a configuration file in which several aspects of Gtk3 can be configured. Examples are the theme, the default font and size, scrollbar behaviour, ...
+
;For GnuCash version 2.6 and earlier:
:The full list of configurable parameters can be found on the [https://developer.gnome.org/gtk3/stable/GtkSettings.html Gtk Settings page]
+
:;Linux and MacOS: <tt>.gtkrc-2.0.gnucash</tt> (note the initial ".")
;gtk.css: a css file for styling Gtk widgets. Any css changes in this file will override overlapping style information in the current theme so this can be used to tweak the theme in more detail.
+
:;Windows: <tt>.gtkrc-2.0</tt> and <tt>.gtkrc-2.0.gnucash</tt> (again, note the initial ".")
 +
:Windows users should note that it's best not to make manual changes to .gtkrc-2.0, since it will get overwritten when you use the "Select Theme" tool. Instead you should put your customizations in '''<tt>.gtkrc-2.0.gnucash</tt>''', since changes made in this file will only be read by GnuCash and will not be overwritten when you use the "Select Theme" tool.
 +
:Additionally, there is actually a third, system-wide, resource file: '''<tt>c:\Program Files (x86)\gnucash\etc\gtk-2.0\gtkrc</tt>'''. Changes made to this file will be seen by ''all users'' of your computer. When you enable the option "Apply to all users" in the "Select Theme" tool it will alter this file. Keep in mind that changes in this file may be overwritten when you update GnuCash to a newer version.
 +
:There is some more information on [[GTK2]].
  
More information on how these file are used can be found on our [[GTK3]] page. That page has several examples as well.
+
==In GNC_CONFIG_HOME ==
 
 
=== In GNC_CONFIG_HOME ===
 
  
 
;config-user.scm: this file is the entry point to extend GnuCash by means of the guile scripting language. It's most often used to load additional reports but us not restricted to only that.
 
;config-user.scm: this file is the entry point to extend GnuCash by means of the guile scripting language. It's most often used to load additional reports but us not restricted to only that.
;gtk-3.0.css: like GTK_CONFIG_HOME's gtk.css this file can be used to manipulate styling for Gtk widgets. Any css changes in this file will override overlapping style info in gtk.css (and hence the current theme as well).
+
;gtk-3.0.css: like GTK_CONFIG_HOME's gtk.css this file can be used to manipulate styling for GTK widgets. Any css changes in this file will override overlapping style info in gtk.css (and hence the current theme as well).
:The difference between GTK_CONFIG_HOME's gtk.css and GNC_CONFIG_HOME's gtk-3.0.css is subtle: gtk-3.0.css will only affect GnuCash while gtk.css may also affect other gtk based applications on your system (for example gimp,...)
+
:The difference between GTK_CONFIG_HOME's gtk.css and GNC_CONFIG_HOME's gtk-3.0.css is subtle: gtk-3.0.css will only affect GnuCash while gtk.css may also affect other GTK-based applications on your system (for example gimp).
 
;log.conf: via this file you can manipulate how much information GnuCash will write to a log file. By default this is pretty mild. To help developers in debugging problems the verbosity can be increased.
 
;log.conf: via this file you can manipulate how much information GnuCash will write to a log file. By default this is pretty mild. To help developers in debugging problems the verbosity can be increased.
  
=== In DOT_GNUCASH_DIR ===
+
== In DOT_GNUCASH_DIR ==
  
 
All files and directories found in GNC_CONFIG_HOME and GNC_DATA_HOME, with one exception: config-user.scm is called config.user in 2.6 and before.
 
All files and directories found in GNC_CONFIG_HOME and GNC_DATA_HOME, with one exception: config-user.scm is called config.user in 2.6 and before.
  
 +
== In HOME ==
  
== How to override default locations ==
+
'''Versions:''' 2.6.x and older
  
The [[#Directories]] section above shows default locations used on different operating systems. Sometimes there locations are not convenient. There are several ways to alter them (or your system already alters them for you using one of the below methods).
+
;.gtkrc-2.0: this file can be edited to tweak gtk2's default behaviour and appearance. On Linux and Macos this is a hidden file
 +
;.gtkrc-2.0-gnucash: like .gtkrc-2.0, but will affect GnuCash only while .gtkrc-2.0 will affect other gtk2 based applications on your system
  
=== Environment variable DOT_GNUCASH_DIR ===
+
= How to override default locations =
 +
 
 +
The [[#Directories]] section shows default locations used on different operating systems. Sometimes there locations are not convenient. There are several ways to alter them (or your system already alters them for you using one of the below methods).
 +
 
 +
== Environment variable DOT_GNUCASH_DIR ==
  
 
'''Platforms:''' All
 
'''Platforms:''' All
Line 150: Line 178:
 
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as DOT_GNUCASH_DIR, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
 
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as DOT_GNUCASH_DIR, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
  
=== Environment variable GNC_DATA_HOME ===
+
== Environment variable GNC_DATA_HOME ==
  
 
'''Platforms:''' All
 
'''Platforms:''' All
Line 157: Line 185:
 
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_DATA_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
 
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_DATA_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
  
=== Environment variable XDG_DATA_HOME ===
+
== Environment variable GNC_CONFIG_HOME ==
 +
 
 +
'''Platforms:''' All
 +
'''Versions:''' 3.4 and more recent
 +
 
 +
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_CONFIG_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
 +
 
 +
== Environment variable XDG_DATA_HOME ==
  
 
'''Platforms:''' Linux, MacOS
 
'''Platforms:''' Linux, MacOS
Line 165: Line 200:
 
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
 
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
  
=== Environment variable XDG_CONFIG_HOME ===
+
== Environment variable XDG_CONFIG_HOME ==
  
 
'''Platforms:''' Linux, MacOS
 
'''Platforms:''' Linux, MacOS
Line 175: Line 210:
 
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
 
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
  
=== Environment variables LOCALAPPDATA and APPDATA ===
+
== Environment variables LOCALAPPDATA and APPDATA ==
  
 
'''Platforms:''' Windows
 
'''Platforms:''' Windows
Line 183: Line 218:
 
Note you probably don't want to change these environment variables system wide as that would affect all applications on your system.
 
Note you probably don't want to change these environment variables system wide as that would affect all applications on your system.
  
=== File environment.local ===
+
== File environment.local ==
  
 
'''Platforms:''' All
 
'''Platforms:''' All
Line 191: Line 226:
  
 
;Linux: <tt>/etc/gnucash/environment</tt> or more generally <tt><installprefix>/etc/gnucash/environment</tt>
 
;Linux: <tt>/etc/gnucash/environment</tt> or more generally <tt><installprefix>/etc/gnucash/environment</tt>
;Windows: <tt>c:\Program Files(x86)\GnuCash\etc\gnucash\environment</tt>
+
;Windows: <tt>C:\Program Files (x86)\gnucash\etc\gnucash\environment</tt>
 
;MacOS: <tt><GnuCash.app>/Resources/etc/GnuCash/environment</tt>
 
;MacOS: <tt><GnuCash.app>/Resources/etc/GnuCash/environment</tt>
  
 
The format of the environment.local file is explained at the top of the environment file.
 
The format of the environment.local file is explained at the top of the environment file.
  
;Note: while on MacOS this works there is an issue when updating gnucash. Each time you update your gnucash package environment.local will be removed. So you may want to keep a copy of the file outside of the application bundle that you can put back after each update.
+
;Note: while on MacOS this works there is an issue when updating GnuCash. Each time you update your GnuCash package environment.local will be removed. So you may want to keep a copy of the file outside of the application bundle that you can put back after each update.

Revision as of 03:51, 16 February 2019

Introduction

GnuCash stores several categories of information regarding your setup in several locations on your machine. In addition to your financial data file itself, there are configuration settings that control how your copy of GnuCash looks and acts, and there are custom report settings.

This page focuses on the files and locations of configuration settings under the different operating systems that GnuCash supports.

Important Note
Your Financial data file(s) are not located in any pre-specified location. They are located wherever you have chosen to place them on your system.

GnuCash will read several configuration files in different directories. And several pages on this wiki will refer to one or more of these. As these directories often differ between operating systems and may be overridden in several ways, this page will attempt to give an overview. What each file does can be found on other pages instead.

Note: Unless described more specifically, the following general operating systems definitions will be used:

Linux
including many similar operating systems that adhere to the Free Desktop specification like various BSD flavors,
Windows
for all supported Windows versions
MacOS (formerly OS X)
for the version of GnuCash that is built with Quartz integration, and can be downloaded from the GnuCash website. On MacOS there is also a MacPorts version of GnuCash. Except for the MacOS proper home directory it behaves identical to Linux and variants. So it will only be listed in the HOME directory definition.

Directories

Let's start with defining a few common directory locations that will be referred to regularly.

HOME

The user's home directory on your computer. While this may be obvious, it is mentioned here because it's the base directory for several others below. The usual locations per OS are:

Linux
/home/<username> - for example /home/johndoe
Note that this directory is also often referred to as $HOME or ~/
Windows 7 and more recent
c:\Users\<username> - for example c:\Users\johndoe
Windows Vista and older
c:\Documents and settings\<username> - for example c:\Documents and settings\johndoe
MacOS, MacPorts
/Users/<username> - for example /Users/johndoe

In the following directories, this base directory will be referred to as HOME.

USER_DATA_HOME

This directory can be used by applications to store data that can't be stored in the user's data file for some reason. For example gnucash will store saved reports here, or some metadata such as which register tabs were open for your books last time you closed them. The default locations:

Linux
HOME/.local/share
Windows
On this platform there are actually two directories for this kind of data:
HOME\AppData\Local, often referred to as %LOCALAPPDATA%
HOME\AppData\Roaming, often referred to as %APPDATA%
The reason for having two is not important in the scope of this page.
Note %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
MacOS
On this platform there are actually two directories for this kind of data:
HOME/Library/Application Support (or HOME/Library/Applications Defaults for OS X 10.6 and older)
HOME/.local/share
The former is native to MacOS (and will be used by GnuCash), the latter is often used by software that's ported from linux (like GTK3). The difference will get clearer further down.

It's important to understand this directory is shared by all applications you run on your system. So aside from GnuCash, applications like Firefox, Microsoft Office, LibreOffice and so on will also write here. To avoid clutter, most applications have the courtesy to create their own subdirectory here and only write in that subdirectory. This leads seamlessly to the next couple of important directories:

GNC_DATA_HOME

Versions: 3.x and more recent

This is the subdirectory in USER_DATA_HOME that GnuCash uses exclusively for its user specific data. The default locations:

Linux
USER_DATA_HOME/gnucash
Windows
%APPDATA%\GnuCash
MacOS
HOME/Library/Application Support/GnuCash

Note that on Windows the base directory is APPDATA and on MacOS this is HOME/Library/Application Support. The base directories will be different for the next relevant directory:

GTK_DATA_HOME

Versions: 3.x and more recent

GnuCash uses GTK for its graphical user interface; thus, locations that are used by GTK are also relevant. Note the base directories on Windows and MacOS for this differ from the base directories for GNC_DATA_HOME.

Linux
USER_DATA_HOME/gtk-3.0
Windows
%LOCALAPPDATA%\gtk-3.0
MacOS
HOME/.local/share/gtk-3.0

USER_CONFIG_HOME

This directory is used for configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows, for example, there is no difference between the two and USER_DATA_HOME will be used. On Linux, GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). GTK3 seems to maintain a similar strategy. On MacOS, it's a bit more complicated; GnuCash will use USER_DATA_HOME for all its own configuration files, but another directory for all of its support libraries.

Default locations:

Linux
HOME/.config
Windows
There are two directories for this kind of data:
HOME\AppData\Local, often referred to as %LOCALAPPDATA%
HOME\AppData\Roaming, often referred to as %APPDATA%
The reason for having two is not important in the scope of this page.
Note %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
MacOS
There are two directories for this kind of data:
HOME/Library/Application Support
HOME/Library/Application Support/config
The former is native to MacOS (and will be used by GnuCash), the latter is what GnuCash configures for all its support libraries (like GTK3).

Like USER_DATA_HOME USER_CONFIG_HOME is common for all applications. Each application will typically expect an application specific subdirectory here.

GNC_CONFIG_HOME

Versions: 3.x and more recent

This is the subdirectory in USER_CONFIG_HOME GnuCash uses exclusively for its user specific configuration data. The default locations:

Linux
USER_CONFIG_HOME/gnucash
Windows
%APPDATA%\GnuCash
MacOS
HOME/Library/Application Support/GnuCash

Note that on Windows, the base directory is APPDATA and on MacOS, this is HOME/Library/Application Support. The base directories will be different for the next relevant directory:

GTK_CONFIG_HOME

GnuCash uses GTK for its graphical user interface; thus, locations that are used by GTK are also relevant. The folders differ by GnuCash version.

  • For GnuCash 2.6.x and older, GTK uses the HOME directory for resource files.
  • For GnuCash 3.0 and later. Note the base directories on Windows and MacOS for this differ from the base directories for GNC_DATA_HOME.
Linux
USER_CONFIG_HOME/gtk-3.0
Windows
%LOCALAPPDATA%\gtk-3.0
MacOS
HOME/Library/Application Support/GnuCash/config/gtk-3.0

DOT_GNUCASH_DIR

Versions: 2.6.x and older

GnuCash 2.6 and older don't distinguish between #GNC_DATA_HOME and #GNC_CONFIG_HOME. Instead, these versions of GnuCash store both metadata and configuration files in a single directory. The default locations are:

Linux
HOME/.gnucash
Windows
HOME\.gnucash
MacOS
HOME/Library/Application Support/Gnucash

For GnuCash 3.0 and up, these files have been moved to different locations to integrate better with each supported platform's recommended locations. When moving from GnuCash 2.6 to 3.x or above, GnuCash will automatically try to migrate all data from DOT_GNUCASH_DIR to their respective new locations. After mitgration, GnuCash 3.0 or above should never use DOT_GNUCASH_DIR again.

Files

With the most common base directories defined, we can now create a reference list of relevant data and configuration files in each of these directories.

In GNC_DATA_HOME

As noted, GnuCash manages these files for you. So usually there's no need to manipulate these by hand. If you do need to make changes be sure to do so while GnuCash is not running.

accelerator-map
A file in which custom accelerator key bindings are stored.
books/<name>.gcm
GnuCash tracks all metadata related to a book in this file. There will usually be one such file for each book you have ever created/opened. This metadata includes things like window positions, sort orders, which columns to show, CSV import presets,... See Metadata_File for more details.
checks
A directory to hold custom check formats.
Note for developers: this should probably live in GNC_CONFIG_HOME as this is mostly user configurable data.
expressions-2.0
A file to contain custom expressions managed by the GnuCash expression parser.
Note for developers: This file needs more documentation.
qif-accounts-map
Used by the qif importer to keep track of mappings between qif account references and gnucash accounts. This file is formatted in the guile scripting language.
saved-reports-x.y
This file keeps track of all saved report configurations you have created in gnucash. There may be more than one such file with different numbers in x.y. Normally the highest number is the active file while those with lower numbers are kept as a backup (they were the main file for older versions of gnucash). As qif-accounts-map this file is formatted in the guile scripting language.
stylesheets-2.0
This file keeps track of all personalized style sheets for reports. This file is formatted in the guile scripting language as well.

In GTK_CONFIG_HOME

For GnuCash version 3.0 and later
settings.ini
a configuration file in which several aspects of GTK3 can be configured. Examples are the theme, the default font and size, scrollbar behaviour, ...
The full list of configurable parameters can be found on the GTK Settings page
gtk.css
a CSS file for styling GTK widgets. Any css changes in this file will override overlapping style information in the current theme so this can be used to tweak the theme in more detail.
gtk-3.0.css
a second css file that will take precedence over the information in gtk.css.
More information on how these file are used can be found at the GTK3 page. That page has several examples as well.
For GnuCash version 2.6 and earlier
Linux and MacOS
.gtkrc-2.0.gnucash (note the initial ".")
Windows
.gtkrc-2.0 and .gtkrc-2.0.gnucash (again, note the initial ".")
Windows users should note that it's best not to make manual changes to .gtkrc-2.0, since it will get overwritten when you use the "Select Theme" tool. Instead you should put your customizations in .gtkrc-2.0.gnucash, since changes made in this file will only be read by GnuCash and will not be overwritten when you use the "Select Theme" tool.
Additionally, there is actually a third, system-wide, resource file: c:\Program Files (x86)\gnucash\etc\gtk-2.0\gtkrc. Changes made to this file will be seen by all users of your computer. When you enable the option "Apply to all users" in the "Select Theme" tool it will alter this file. Keep in mind that changes in this file may be overwritten when you update GnuCash to a newer version.
There is some more information on GTK2.

In GNC_CONFIG_HOME

config-user.scm
this file is the entry point to extend GnuCash by means of the guile scripting language. It's most often used to load additional reports but us not restricted to only that.
gtk-3.0.css
like GTK_CONFIG_HOME's gtk.css this file can be used to manipulate styling for GTK widgets. Any css changes in this file will override overlapping style info in gtk.css (and hence the current theme as well).
The difference between GTK_CONFIG_HOME's gtk.css and GNC_CONFIG_HOME's gtk-3.0.css is subtle: gtk-3.0.css will only affect GnuCash while gtk.css may also affect other GTK-based applications on your system (for example gimp).
log.conf
via this file you can manipulate how much information GnuCash will write to a log file. By default this is pretty mild. To help developers in debugging problems the verbosity can be increased.

In DOT_GNUCASH_DIR

All files and directories found in GNC_CONFIG_HOME and GNC_DATA_HOME, with one exception: config-user.scm is called config.user in 2.6 and before.

In HOME

Versions: 2.6.x and older

.gtkrc-2.0
this file can be edited to tweak gtk2's default behaviour and appearance. On Linux and Macos this is a hidden file
.gtkrc-2.0-gnucash
like .gtkrc-2.0, but will affect GnuCash only while .gtkrc-2.0 will affect other gtk2 based applications on your system

How to override default locations

The #Directories section shows default locations used on different operating systems. Sometimes there locations are not convenient. There are several ways to alter them (or your system already alters them for you using one of the below methods).

Environment variable DOT_GNUCASH_DIR

Platforms: All Versions: 2.6.x and older

When a directory is specified via this environment variable GnuCash will unconditionally use that directory as DOT_GNUCASH_DIR, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.

Environment variable GNC_DATA_HOME

Platforms: All Versions: 3.x and more recent

When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_DATA_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.

Environment variable GNC_CONFIG_HOME

Platforms: All Versions: 3.4 and more recent

When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_CONFIG_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.

Environment variable XDG_DATA_HOME

Platforms: Linux, MacOS

This environment variable can be used to directly set USER_DATA_HOME. As such it will affect the base directory for GNC_DATA_HOME and GTK_DATA_HOME. On MacOS this will only affect GTK_DATA_HOME.

Note
The Directories page has some background information on the origin of the XDG_ environment variables.

Environment variable XDG_CONFIG_HOME

Platforms: Linux, MacOS

This environment variable can be used to directly set USER_CONFIG_HOME. As such it will affect the base directory for GNC_CONFIG_HOME and GTK_CONFIG_HOME. On MacOS this will only affect GTK_CONFIG_HOME.

There is a caveat here though: on MacOS GnuCash will set XDG_CONFIG_HOME itself via <bundle>/Resources/etc/gnucash/environment. The only way to override XDG_CONFIG_HOME on this platform is via #File environment.local and this should be repeated each time a GnuCash update is installed.

Note
The Directories page has some background information on the origin of the XDG_ environment variables.

Environment variables LOCALAPPDATA and APPDATA

Platforms: Windows

By setting these environment variables USER_DATA_HOME (and by extension USER_CONFIG_HOME) can be set directly on Windows. Hence depending on which of these two is altered this directly affects GNC_DATA_HOME/GNC_CONFIG_HOME (in case of APPDATA) or GTK_DATA_HOME/GTK_CONFIG_HOME (in case of LOCALAPPDATA).

Note you probably don't want to change these environment variables system wide as that would affect all applications on your system.

File environment.local

Platforms: All Versions: 3.x and more recent

All of the above environment variables can also be set for GnuCash only by creating a file named environment.local next to the file named environment in the gnucash installation. The typical location for this environment file is platform dependent:

Linux
/etc/gnucash/environment or more generally <installprefix>/etc/gnucash/environment
Windows
C:\Program Files (x86)\gnucash\etc\gnucash\environment
MacOS
<GnuCash.app>/Resources/etc/GnuCash/environment

The format of the environment.local file is explained at the top of the environment file.

Note
while on MacOS this works there is an issue when updating GnuCash. Each time you update your GnuCash package environment.local will be removed. So you may want to keep a copy of the file outside of the application bundle that you can put back after each update.