Configuration Locations

This article describes the configuration file locations as they related to GnuCash v3.0. Originally posted by Geert in a mailing list thread.

TODO: Overlaps with Directories.

GnuCash 3.0 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.

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 I'm mentioning it here as it's the base directory for several others below. The usual locations per OS are:

Linux

/home/<username> - for example /home/johndoe

Note that in a linux context this directory is also often referred to as $HOME or ~/

Windows

c:\Users\<username> - for example c:\Users\johndoe

Macos (formerly OS X)

/Users/<username> - for example /Users/johndoe

In the following directories I will simply refer to this base directory 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.

Macos (formerly OS X)

On this platform there are actually two directories for this kind of data:

HOME/Library/Application Support

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 in here and only write in that subdirectory. This leads us seamlessly to the next couple of important directories:

GNC_DATA_HOME

This is the subdirectory in USER_DATA_HOME the gnucash exclusively uses for it's user specific data. The default locations:

Linux

USER_DATA_HOME/gnucash

Windows

%APPDATA%\GnuCash

Macos (formerly OS X)

HOME/Library/Application Support/GnuCash

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:

GTK_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

USER_DATA_HOME/gtk-3.0

Windows

%LOCALAPPDATA%\gtk-3.0

Macos (formerly OS X)

HOME/.local/share/gtk-3.0

Files

Gtk3: settings.ini

Directory

GTK_CONFIG_HOME

Gtk3: gtk.css

Directory

GTK_CONFIG_HOME

GnuCash: gtk-3.0.css

Directory

GNC_CONFIG_HOME

TODO integrate background info below

XDG_* Variables

The XDG_* variables come from a free desktop specification (1) that defines a number standard directories and paths that each system that claims to follow this standard should adhere to. Most desktop environments (kde, gnome, xfce,...) on linux do adhere to this so they can interoperate properly. Many programs rely on this, and gnucash is no exception as it's based on gtk (which underpins the gnome desktop environment as well).

There are two that gnucash uses as of gnucash 3.0 and related to user data:

XDG_DATA_HOME

(defaults to ~/.local/share on linux)

XDG_CONFIG_HOME

(defaults to ~/.config on linux)

On systems that follow the XDG specification, users can override either by setting environment variables with these names. In practice this is everywhere except on Windows and in the Quartz version of gnucash. Both of these instead use the platform specific default paths and will ignore the XDG_* settings [2].

As you may observe neither path is specific to gnucash. These directories are shared by all applications adherering to the above specification. So in order to keep these directories tidy, most applications make an application specific subdirectory in there. For gnucash on linux these are (predictably)

~/.local/share/gnucash
~/.config/gnucash

The former can be overridden by setting GNC_DATA_HOME, the latter can't be overridden (that's an oversight, not intentional).

Lastly, the 2.6 .gnucash dir has no one to one mapping to a directory under 3.0. In fact it's content has been distributed over the two directories above. The rationale is this:

Any configuration file we expect the user to tweak manually should go in config/gnucash. GnuCash will never alter any file in there (except for the one-time initial migration. Any file we don't expect the user to tweak manually (as it's written and maintained by gnucash itself) should go into local/share/gnucash. We expect users to not touch these files directly and gnucash can overwrite these at any time.

Files that should go in .config are things like a customized css file, a config file with custom scheme code, ...

Files that still go in .local/share are saved reports (gnucash manages these), state files, style sheets,...

Currently the accelerator-maps are also still stored in there, but I believe this is a mistake as well that should be corrected at some point.

Windows

The user configuration directory is %APPDATA%\GnuCash. The %APPDATA% variable by default points to C:\Users\<userid>\AppData\Roaming. Note that AppData is a hidden folder.