Difference between revisions of "Configuration Locations"
(→In GTK_CONFIG_HOME: /etc/gtk<version>) |
Agielchinsky (talk | contribs) (config files can be found at Help -> About) |
||
(37 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
− | 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, | + | 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, including | ||
+ | ** ''custom report settings'', ''key binding map''s… Finally there are | ||
+ | * ''dynamic data'' like log files, downloaded statements and more. | ||
− | ''This page focuses on the files and locations of configuration settings under the different operating systems that GnuCash supports.'' | + | ''This page focuses on the files and locations of configuration settings under the different operating systems that GnuCash supports.'' They are derived from the [[Directory Standards]]. |
+ | |||
+ | If you want to check where the configuration files are located on your system go to Help -> About. | ||
+ | |||
+ | [[category: Installation]] [[category: Configuration]] [[category: Usage]] | ||
=Introduction= | =Introduction= | ||
Line 13: | Line 21: | ||
::;Windows: %VARNAME% | ::;Windows: %VARNAME% | ||
:;Build variables: exist only while the program gets build, but have default values. Usually their first occurrence in a section links to the section, which explains where to find it on which OS. | :;Build variables: exist only while the program gets build, but have default values. Usually their first occurrence in a section links to the section, which explains where to find it on which OS. | ||
− | + | :;Meaning of Name Parts: | |
− | ''' | + | ::;DOT: a hidden configurattion directory, used up to Gnucash 2 |
− | + | ::;GNC: GnuCash specific | |
− | :;Linux: including many similar operating systems that adhere to the Free Desktop specification like various | + | ::;GTK: The former ''Gimp ToolKit'' is used by Gnucash [[GTK3|since 3]] and [[GTK2|before]]. |
+ | ::;XDG: The former ''X Desktop Group'' is today known as [{{URL:XDG}} Freedesktop.org]. The [[Directory Standards]] page has some background information on the origin of the XDG_ environment variables. | ||
+ | ;Operating Systems: 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 | :;Windows: for all supported Windows versions | ||
:;macOS: for the version of GnuCash that is built with ''Quartz'' integration, and can be downloaded from the GnuCash website. | :;macOS: for the version of GnuCash that is built with ''Quartz'' integration, and can be downloaded from the GnuCash website. | ||
− | :: | + | ::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|HOME]] directory definition. |
− | + | :;Note: GnuCash installed from [[Flatpak]], snap or similar package systems may not locate meta data and user preference data as described here. Flatpak keeps them in its GnuCash sandbox | |
− | + | ::<tt>$[[#HOME|HOME]]/.var/app/{{GSettings Path|.}}</tt>. | |
= Diagrams of Configuration Locations = | = Diagrams of Configuration Locations = | ||
Line 33: | Line 44: | ||
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. | ||
+ | == System-wide== | ||
+ | System-wide configuration files can be made by the programmers or packagers. They can only be changed by the system administrator and will affect all users. | ||
+ | |||
+ | The system-wide setting valid for GnuCash and its helpers are stored below: | ||
+ | ;Linux: | ||
+ | :;pristine: <tt>/etc/</tt> followed by the package name like <tt>gnucash</tt>, <tt>gtk</tt>… | ||
+ | :;Flatpak: installed for | ||
+ | ::;All users: <tt>/var/lib/flatpak/app/{{GSettings Path|.}}/current/active/files/etc</tt> | ||
+ | ::;Single user: <tt> $HOME/.local/share/flatpak/app/{{GSettings Path|.}}/current/active/files/etc</tt> | ||
+ | ::Instead of creating an [[#File_environment.local|environment.local]] file which will not persist across flatpak updates, custom environment variables should be set by | ||
+ | ::<Syntaxhighlight lang="sh"> | ||
+ | [sudo] flatpak override (--user|--system) --env=VAR="VALUE" org.gnucash.GnuCash | ||
+ | # E.g. | ||
+ | # Note sudo is required for "--system" app overrides but not for "--user" | ||
+ | sudo flatpak override --system --env=LANG="en_GB.utf8" --env=LANGUAGE="en_GB" org.gnucash.GnuCash | ||
+ | </Syntaxhighlight> | ||
+ | ::Environment variables set this way will be set for all following runs of the app, and persist across flatpak updates. You can check your environment variable overrides by | ||
+ | ::<Syntaxhighlight lang="sh"> | ||
+ | flatpak override --show org.gnucash.GnuCash | ||
+ | </Syntaxhighlight> | ||
+ | ;{{mac}}: <tt>Gnucash.app/Contents/Resources/etc</tt> | ||
+ | :;Caution: On recent {{mac}}es changes made here will invalidate the signature. | ||
+ | ;Windows: <tt>C:\Program Files (x86)\gnucash\etc</tt> | ||
+ | |||
+ | == Personal == | ||
+ | Files here can be changed by the respective user and will only affect them. | ||
− | == 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 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 45: | Line 82: | ||
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: |
;Linux: | ;Linux: | ||
:;pristine: <tt>$[[#HOME|HOME]]/.local/share</tt> | :;pristine: <tt>$[[#HOME|HOME]]/.local/share</tt> | ||
− | :;[[Flatpak]]: <tt>$[[#HOME|HOME]]/.var/app/ | + | :;[[Flatpak]]: <tt>$[[#HOME|HOME]]/.var/app/{{GSettings Path|.}}/data</tt> |
;Windows: On this platform there are actually two directories for this kind of data: | ;Windows: On this platform there are actually two directories for this kind of data: | ||
− | :<tt>[[#HOME|HOME]]\AppData\Local</tt>, often referred to as [[#Environment variables LOCALAPPDATA and APPDATA|%LOCALAPPDATA%]] | + | :;Local—machine specific: |
− | :<tt>[[#HOME|HOME]]\AppData\Roaming</tt>, often referred to as [[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]] | + | ::* The machine is no member of a Windows domain '''or''' |
− | + | ::* the user has choosen a (machine) local profile on login: | |
+ | ::<tt>[[#HOME|HOME]]\AppData\Local</tt>, often referred to as [[#Environment variables LOCALAPPDATA and :APPDATA|%LOCALAPPDATA%]] | ||
+ | :;Roaming—domain wide: | ||
+ | ::* The machine is member of a Windows domain '''and''' | ||
+ | ::* the user has choosen a domain wide profile on login: | ||
+ | ::<tt>[[#HOME|HOME]]\AppData\Roaming</tt>, often referred to as [[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]] | ||
;macOS: On this platform there are actually two directories for this kind of data: | ;macOS: On this platform there are actually two directories for this kind of data: | ||
:;native: | :;native: | ||
Line 64: | Line 106: | ||
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: | 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 | ||
Line 71: | Line 113: | ||
;Linux: | ;Linux: | ||
:;pristine: <tt>[[#USER_DATA_HOME|USER_DATA_HOME]]/gnucash</tt> | :;pristine: <tt>[[#USER_DATA_HOME|USER_DATA_HOME]]/gnucash</tt> | ||
− | :;Flatpak: <tt>$[[#HOME|HOME]]/.var/app/ | + | :;Flatpak: <tt>$[[#HOME|HOME]]/.var/app/{{GSettings Path|.}}/data/gnucash</tt> |
;Windows: <tt>[[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]]\GnuCash</tt> | ;Windows: <tt>[[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]]\GnuCash</tt> | ||
;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash</tt> | ;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash</tt> | ||
Line 77: | Line 119: | ||
Note that on Windows the base directory is ''[[#Environment variables LOCALAPPDATA and APPDATA|APPDATA]]'' and on macOS this is ''[[#HOME|HOME]]/Library/Application Support''. The base directories will be different for the next relevant directory: | Note that on Windows the base directory is ''[[#Environment variables LOCALAPPDATA and APPDATA|APPDATA]]'' and on macOS this is ''[[#HOME|HOME]]/Library/Application Support''. The base directories will be different for the next relevant directory: | ||
− | == GTK_DATA_HOME == | + | === GTK_DATA_HOME === |
'''Versions:''' 3.x and more recent only | '''Versions:''' 3.x and more recent only | ||
Line 87: | Line 129: | ||
;macOS: <tt>[[#HOME|HOME]]/.local/share/gtk-3.0</tt> | ;macOS: <tt>[[#HOME|HOME]]/.local/share/gtk-3.0</tt> | ||
− | == USER_CONFIG_HOME == | + | === 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|USER_DATA_HOME]] will be used. On Linux, GnuCash will roughly make a distinction on whether the file is intended to be rarely created/modified ''by the user'' ([[#USER_CONFIG_HOME|USER_CONFIG_HOME]]) or often ''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. | 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|USER_DATA_HOME]] will be used. On Linux, GnuCash will roughly make a distinction on whether the file is intended to be rarely created/modified ''by the user'' ([[#USER_CONFIG_HOME|USER_CONFIG_HOME]]) or often ''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. | ||
Line 93: | Line 135: | ||
;Linux: | ;Linux: | ||
:;pristine:<tt>$[[#HOME|HOME]]/.config</tt> | :;pristine:<tt>$[[#HOME|HOME]]/.config</tt> | ||
− | :;[[Flatpak]]: <tt>$[[#HOME|HOME]]/.var/app/ | + | :;[[Flatpak]]: <tt>$[[#HOME|HOME]]/.var/app/{{GSettings Path|.}}/config</tt> |
;Windows: There are two directories for this kind of data: | ;Windows: There are two directories for this kind of data: | ||
:<tt>[[#HOME|HOME]]\AppData\Local</tt>, often referred to as [[#Environment variables LOCALAPPDATA and APPDATA|%LOCALAPPDATA%]] | :<tt>[[#HOME|HOME]]\AppData\Local</tt>, often referred to as [[#Environment variables LOCALAPPDATA and APPDATA|%LOCALAPPDATA%]] | ||
Line 101: | Line 143: | ||
:<tt>[[#HOME|HOME]]/Library/Application Support</tt> | :<tt>[[#HOME|HOME]]/Library/Application Support</tt> | ||
:<tt>[[#HOME|HOME]]/.config</tt> | :<tt>[[#HOME|HOME]]/.config</tt> | ||
− | :The former is native to macOS (and will be used by GnuCash), the latter is the default for [ | + | :The former is native to macOS (and will be used by GnuCash), the latter is the default for [{{URL:XDG-spec}}basedir-spec/basedir-spec-latest.html XDG_CONFIG_HOME] and Gtk uses that variable. |
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 only | '''Versions:''' 3.x and more recent only | ||
Line 112: | Line 154: | ||
;Linux: | ;Linux: | ||
:;pristine: <tt>[[#USER_CONFIG_HOME|USER_CONFIG_HOME]]/gnucash</tt> | :;pristine: <tt>[[#USER_CONFIG_HOME|USER_CONFIG_HOME]]/gnucash</tt> | ||
− | :;Flatpak: <tt>$[[#HOME|HOME]]/.var/app/ | + | :;Flatpak: <tt>$[[#HOME|HOME]]/.var/app/{{GSettings Path|.}}/config/gnucash</tt> |
;Windows: <tt>[[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]]\GnuCash</tt> | ;Windows: <tt>[[#Environment variables LOCALAPPDATA and APPDATA|%APPDATA%]]\GnuCash</tt> | ||
;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash</tt> | ;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash</tt> | ||
Line 118: | Line 160: | ||
Note that on Windows, the base directory is ''[[#Environment variables LOCALAPPDATA and APPDATA|APPDATA]]'' and on macOS, this is ''[[#HOME|HOME]]/Library/Application Support''. The base directories will be different for the next relevant directory: | Note that on Windows, the base directory is ''[[#Environment variables LOCALAPPDATA and APPDATA|APPDATA]]'' and on macOS, this is ''[[#HOME|HOME]]/Library/Application Support''. The base directories will be different for the next relevant directory: | ||
− | == GTK_CONFIG_HOME == | + | === 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. | GnuCash uses GTK for its graphical user interface; thus, locations that are used by GTK are also relevant. The folders differ by GnuCash version. | ||
Line 129: | Line 171: | ||
:;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash/config/gtk-3.0</tt> | :;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/GnuCash/config/gtk-3.0</tt> | ||
− | == DOT_GNUCASH_DIR == | + | === DOT_GNUCASH_DIR === |
'''Versions:''' 2.6.x and older only | '''Versions:''' 2.6.x and older only | ||
Line 138: | Line 180: | ||
;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/Gnucash</tt> | ;macOS: <tt>[[#HOME|HOME]]/Library/Application Support/Gnucash</tt> | ||
− | 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. | + | In the same way [[Aqbanking]] creates a folder <tt>$[[#HOME|HOME]]/.aqbanking</tt> and is still using it for configuration, logs … |
+ | |||
+ | 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 = | ||
Line 148: | Line 192: | ||
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. | 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. If you need to edit them, please read [[GTK3#Menu_Keyboard_Shortcuts]]. |
;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. | ;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. | ||
Line 162: | Line 206: | ||
;For GnuCash version 3.0 and later: | ;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, ... | :;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 [ | + | ::The full list of configurable parameters can be found on the [{{URL:Gnome-dev}}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.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. | :;gtk-3.0.css: a second css file that will take precedence over the information in gtk.css. | ||
Line 177: | Line 221: | ||
;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 is 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 is not restricted to only that. | ||
+ | :;Filename Change:Up to 2.6 the file was named <tt>config-user</tt> only! | ||
;gtk-3.0.css: like [[#GTK_CONFIG_HOME|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|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: | :The difference between GTK_CONFIG_HOME's gtk.css and GNC_CONFIG_HOME's gtk-3.0.css is subtle: | ||
Line 193: | Line 238: | ||
;.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: 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 | ;.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 | ||
+ | |||
+ | = GSettings = | ||
+ | |||
+ | Besides the directories and files described above GnuCash also stores a number of ''user'' '''preferences''' in GSettings. This is a user level data store for all kinds of preferences. Most of what is found under <tt>Edit->Preferences</tt> and a few extra ones like the MRU list from the <tt>File</tt> menu are stored in there. GSettings itself doesn't have a particular location to store this information in. Instead it relies on "backends" to do this on its behalf. Which backend is used depends on the platform: | ||
+ | ;Linux: | ||
+ | :;pristine: <tt>dconf</tt> - there's no file location associated with this, data can be viewed or edited with <tt>dconf-editor</tt>. For advanced options see <tt>dconf help</tt>. | ||
+ | :;[[Flatpak]]: | ||
+ | ::;Since Gnucash 4.7: <tt>keyfile</tt> — file with settings in [{{URL:wp}}INI_file ini format] is <tt>$HOME/.var/app/{{GSettings Path|.}}/config/glib-2.0/settings/keyfile</tt> | ||
+ | ::;4.5 and 4.6: <tt>keyfile</tt> — file with settings is <tt>$HOME/.var/app/{{GSettings Path old|.}}/config/glib-2.0/settings/keyfile</tt> | ||
+ | ::;4.4 and older: <tt>dconf</tt> — these versions share the settings on the host system so the same location is used here | ||
+ | ;Windows: <tt>registry</tt> — there's no file location associated with this, data can be viewed or edited with <tt>regedit</tt>. In ''regedit'' the GSettings data for gnucash can be found under | ||
+ | :;Since Gnucash 4.7: <tt>{{GSettings Win Prefix}}{{GSettings Path|\}}</tt>. | ||
+ | :;Up to Gnucash 4.6: <tt>{{GSettings Win Prefix}}{{GSettings Path old|\}}</tt>. | ||
+ | ;{{mac}}: <tt>plists</tt> — stored in | ||
+ | :;Since Gnucash 4.7: <tt>$HOME/Library/Preferences/{{GSettings Path|.}}.plist</tt>, | ||
+ | :;4.6 and older:<tt>$HOME/Library/Preferences/{{GSettings Path old|.}}.plist</tt>. | ||
+ | :Copy the file for backing up or transferring. But don't edit it directly, use <tt>defaults</tt>. | ||
= How to override default locations = | = How to override default locations = | ||
The [[#Directories|Directories]] section shows default locations used on different operating systems. Sometimes these 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). | The [[#Directories|Directories]] section shows default locations used on different operating systems. Sometimes these 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). | ||
+ | |||
+ | To figure out the exact value GnuCash sees, you can create a file named '''config-user.scm''' in <tt>$HOME/.config/gnucash</tt> with this contents: <syntaxhighlight lang="scheme"> | ||
+ | (use-modules (gnucash utilities)) | ||
+ | (gnc:warn "XDG_DATA_DIRS=" (getenv "XDG_DATA_DIRS")) | ||
+ | </syntaxhighlight> | ||
+ | The next time you start gnucash it will print the value of XDG_DATA_DIRS somewhere in the <tt>gnucash.trace</tt> file. Replace XDG_DATA_DIRS by the variable of your interest. | ||
== Environment variable DOT_GNUCASH_DIR == | == Environment variable DOT_GNUCASH_DIR == | ||
− | |||
'''Platforms:''' All | '''Platforms:''' All | ||
'''Versions:''' 2.6.x and older | '''Versions:''' 2.6.x and older | ||
Line 225: | Line 292: | ||
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. | 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. | ||
− | + | If <tt>$XDG_DATA_HOME</tt> is either not set or empty, a default equal to <tt>$HOME/.local/share</tt> should be used. | |
+ | |||
+ | == Environment variable XDG_DATA_DIRS == | ||
+ | |||
+ | '''Platforms:''' Linux, macOS | ||
+ | |||
+ | $XDG_DATA_DIRS defines the ''preference-ordered set'' of base directories to search for data files in addition to the $XDG_DATA_HOME base directory. The directories in $XDG_DATA_DIRS should be seperated with a colon ':'. | ||
+ | |||
+ | If <tt>$XDG_DATA_DIRS</tt> is either not set or empty, a value equal to <tt>/usr/local/share/:/usr/share/</tt> should be used. | ||
== Environment variable XDG_CONFIG_HOME == | == Environment variable XDG_CONFIG_HOME == | ||
Line 235: | Line 310: | ||
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|File environment.local]] and this should be repeated each time a GnuCash update is installed. | 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|File environment.local]] and this should be repeated each time a GnuCash update is installed. | ||
− | + | If <tt>$XDG_CONFIG_HOME</tt> is either not set or empty, a default equal to <tt>$HOME/.config</tt> should be used. | |
+ | |||
+ | == Environment variable XDG_CONFIG_DIRS == | ||
+ | |||
+ | '''Platforms:''' Linux, macOS | ||
+ | |||
+ | $XDG_CONFIG_DIRS defines the preference-ordered set of base directories to search for configuration files in addition to the $XDG_CONFIG_HOME base directory. The directories in $XDG_CONFIG_DIRS should be seperated with a colon ':'. | ||
+ | |||
+ | If <tt>$XDG_CONFIG_DIRS</tt> is either not set or empty, a value equal to <tt>/etc/xdg</tt> should be used. | ||
== Environment variables LOCALAPPDATA and APPDATA == | == Environment variables LOCALAPPDATA and APPDATA == | ||
Line 256: | Line 339: | ||
'''Versions:''' 3.x and more recent | '''Versions:''' 3.x and more recent | ||
− | All of the above environment variables can also be set for GnuCash only by creating a file named <tt>environment.local</tt> | + | All of the above environment variables can also be set for GnuCash only by creating a file named <tt>environment.local</tt> in the same directory as the file named <tt>environment</tt> in the gnucash installation. The typical location for this environment file is platform dependent: |
− | ;Linux: <tt>/etc/gnucash/environment</tt> or more generally <tt><installprefix>/etc/gnucash/environment</tt> | + | ;Linux |
+ | ::;pristine: <tt>/etc/gnucash/environment</tt> or more generally <tt><installprefix>/etc/gnucash/environment</tt> | ||
+ | ::;Flatpak: <tt> see [[#System-wide|System-wide]]</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> | ||
Line 264: | Line 349: | ||
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: | + | ;Note: While on macOS (and Flatpak) 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. Flatpak has a better option, overriding environment variables using the '''flatpak override''' command, see [[#System-wide|System-wide]]. |
Latest revision as of 09:44, 9 February 2024
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, including
- custom report settings, key binding maps… Finally there are
- dynamic data like log files, downloaded statements and more.
This page focuses on the files and locations of configuration settings under the different operating systems that GnuCash supports. They are derived from the Directory Standards.
If you want to check where the configuration files are located on your system go to Help -> About.
Contents
- 1 Introduction
- 2 Diagrams of Configuration Locations
- 3 Directories
- 4 Files
- 5 GSettings
- 6 How to override default locations
- 6.1 Environment variable DOT_GNUCASH_DIR
- 6.2 Environment variable GNC_DATA_HOME
- 6.3 Environment variable GNC_CONFIG_HOME
- 6.4 Environment variable XDG_DATA_HOME
- 6.5 Environment variable XDG_DATA_DIRS
- 6.6 Environment variable XDG_CONFIG_HOME
- 6.7 Environment variable XDG_CONFIG_DIRS
- 6.8 Environment variables LOCALAPPDATA and APPDATA
- 6.9 File environment.local
Introduction
- 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.
- Convention
- Path elements in UPPERCASE are not meant literally but are some kind of a variable.
- Environment variables
- can be used on the command line:
- POSIX (Linux, macOS)
- $VARNAME
- Windows
- %VARNAME%
- Build variables
- exist only while the program gets build, but have default values. Usually their first occurrence in a section links to the section, which explains where to find it on which OS.
- Meaning of Name Parts
-
- DOT
- a hidden configurattion directory, used up to Gnucash 2
- GNC
- GnuCash specific
- GTK
- The former Gimp ToolKit is used by Gnucash since 3 and before.
- XDG
- The former X Desktop Group is today known as Freedesktop.org. The Directory Standards page has some background information on the origin of the XDG_ environment variables.
- Operating Systems
- 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
- for the version of GnuCash that is built with Quartz integration, and can be downloaded from the GnuCash website.
- 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.
- Note
- GnuCash installed from Flatpak, snap or similar package systems may not locate meta data and user preference data as described here. Flatpak keeps them in its GnuCash sandbox
- $HOME/.var/app/org.gnucash.GnuCash.
Diagrams of Configuration Locations
The diagrams at the following links illustrate diagrammatically the directory structure for the GnuCash configuration locations which are described in more detail in the following text.
Directories
Let's start with defining a few common directory locations that will be referred to regularly.
System-wide
System-wide configuration files can be made by the programmers or packagers. They can only be changed by the system administrator and will affect all users.
The system-wide setting valid for GnuCash and its helpers are stored below:
- Linux
-
- pristine
- /etc/ followed by the package name like gnucash, gtk…
- Flatpak
- installed for
- All users
- /var/lib/flatpak/app/org.gnucash.GnuCash/current/active/files/etc
- Single user
- $HOME/.local/share/flatpak/app/org.gnucash.GnuCash/current/active/files/etc
- Instead of creating an environment.local file which will not persist across flatpak updates, custom environment variables should be set by
[sudo] flatpak override (--user|--system) --env=VAR="VALUE" org.gnucash.GnuCash # E.g. # Note sudo is required for "--system" app overrides but not for "--user" sudo flatpak override --system --env=LANG="en_GB.utf8" --env=LANGUAGE="en_GB" org.gnucash.GnuCash
- Environment variables set this way will be set for all following runs of the app, and persist across flatpak updates. You can check your environment variable overrides by
flatpak override --show org.gnucash.GnuCash
- macOS
- Gnucash.app/Contents/Resources/etc
- Caution
- On recent macOSes changes made here will invalidate the signature.
- Windows
- C:\Program Files (x86)\gnucash\etc
Personal
Files here can be changed by the respective user and will only affect them.
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:
- Windows
- On this platform there are actually two directories for this kind of data:
- Local—machine specific
-
- The machine is no member of a Windows domain or
- the user has choosen a (machine) local profile on login:
- HOME\AppData\Local, often referred to as %LOCALAPPDATA%
- Roaming—domain wide
-
- The machine is member of a Windows domain and
- the user has choosen a domain wide profile on login:
- HOME\AppData\Roaming, often referred to as %APPDATA%
- macOS
- On this platform there are actually two directories for this kind of data:
- native
-
- current
- HOME/Library/Application Support
- OS X 10.6 and older
- HOME/Library/Applications Defaults
- by ported software
- 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
-
- pristine
- USER_DATA_HOME/gnucash
- Flatpak
- $HOME/.var/app/org.gnucash.GnuCash/data/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 only
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 rarely created/modified by the user (USER_CONFIG_HOME) or often 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:
- 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.
- macOS
- There are two directories for this kind of data:
- HOME/Library/Application Support
- HOME/.config
- The former is native to macOS (and will be used by GnuCash), the latter is the default for XDG_CONFIG_HOME and Gtk uses that variable.
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 only
This is the subdirectory in USER_CONFIG_HOME GnuCash uses exclusively for its user specific configuration data. The default locations:
- Linux
-
- pristine
- USER_CONFIG_HOME/gnucash
- Flatpak
- $HOME/.var/app/org.gnucash.GnuCash/config/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 only
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:
In the same way Aqbanking creates a folder $HOME/.aqbanking and is still using it for configuration, logs …
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. If you need to edit them, please read GTK3#Menu_Keyboard_Shortcuts.
- 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
This directory serves to personalize the system wide GTK settings. Under Linux the system wide settings are in /etc/gtk<version>.
- 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 is not restricted to only that.
- Filename Change
- Up to 2.6 the file was named config-user only!
- 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 all 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
GSettings
Besides the directories and files described above GnuCash also stores a number of user preferences in GSettings. This is a user level data store for all kinds of preferences. Most of what is found under Edit->Preferences and a few extra ones like the MRU list from the File menu are stored in there. GSettings itself doesn't have a particular location to store this information in. Instead it relies on "backends" to do this on its behalf. Which backend is used depends on the platform:
- Linux
-
- pristine
- dconf - there's no file location associated with this, data can be viewed or edited with dconf-editor. For advanced options see dconf help.
- Flatpak
-
- Since Gnucash 4.7
- keyfile — file with settings in ini format is $HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile
- 4.5 and 4.6
- keyfile — file with settings is $HOME/.var/app/org.gnucash/config/glib-2.0/settings/keyfile
- 4.4 and older
- dconf — these versions share the settings on the host system so the same location is used here
- Windows
- registry — there's no file location associated with this, data can be viewed or edited with regedit. In regedit the GSettings data for gnucash can be found under
- Since Gnucash 4.7
- HKEY_CURRENT_USER\Software\GSettings\org\gnucash\GnuCash.
- Up to Gnucash 4.6
- HKEY_CURRENT_USER\Software\GSettings\org\gnucash.
- macOS
- plists — stored in
- Since Gnucash 4.7
- $HOME/Library/Preferences/org.gnucash.GnuCash.plist,
- 4.6 and older
- $HOME/Library/Preferences/org.gnucash.plist.
- Copy the file for backing up or transferring. But don't edit it directly, use defaults.
How to override default locations
The Directories section shows default locations used on different operating systems. Sometimes these 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).
To figure out the exact value GnuCash sees, you can create a file named config-user.scm in $HOME/.config/gnucash with this contents:(use-modules (gnucash utilities))
(gnc:warn "XDG_DATA_DIRS=" (getenv "XDG_DATA_DIRS"))
The next time you start gnucash it will print the value of XDG_DATA_DIRS somewhere in the gnucash.trace file. Replace XDG_DATA_DIRS by the variable of your interest.
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.
If $XDG_DATA_HOME is either not set or empty, a default equal to $HOME/.local/share should be used.
Environment variable XDG_DATA_DIRS
Platforms: Linux, macOS
$XDG_DATA_DIRS defines the preference-ordered set of base directories to search for data files in addition to the $XDG_DATA_HOME base directory. The directories in $XDG_DATA_DIRS should be seperated with a colon ':'.
If $XDG_DATA_DIRS is either not set or empty, a value equal to /usr/local/share/:/usr/share/ should be used.
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.
If $XDG_CONFIG_HOME is either not set or empty, a default equal to $HOME/.config should be used.
Environment variable XDG_CONFIG_DIRS
Platforms: Linux, macOS
$XDG_CONFIG_DIRS defines the preference-ordered set of base directories to search for configuration files in addition to the $XDG_CONFIG_HOME base directory. The directories in $XDG_CONFIG_DIRS should be seperated with a colon ':'.
If $XDG_CONFIG_DIRS is either not set or empty, a value equal to /etc/xdg should be used.
Environment variables LOCALAPPDATA and APPDATA
Platforms: Windows
LOCALAPPDATA and APPDATA are Windows environment variables.
You may see them referred to as %LOCALAPPDATA% and %APPDATA% because to expand their value in the command line (and other places), you need to put percent signs around the variable name. For example, to see the value of APPDATA from a command promptecho %APPDATA%
Note %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer (File Explorer for Windows 10) you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
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 in the same directory as the file named environment in the gnucash installation. The typical location for this environment file is platform dependent:
- Linux
- pristine
- /etc/gnucash/environment or more generally <installprefix>/etc/gnucash/environment
- Flatpak
- see System-wide
- 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 (and Flatpak) 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. Flatpak has a better option, overriding environment variables using the flatpak override command, see System-wide.