Difference between revisions of "FAQ"

General Frequently Asked Questions (FAQ) about GnuCash

Q: How can I contribute to the GnuCash project?

A: Further answers about this are on the Contributing to GnuCash wiki page.

We're working on a more formal process to help you decide how to contribute, but for now you should subscribe to the Mailing Lists gnucash-user and/or gnucash-devel and discuss what you can contribute with the participants on the lists. Please be aware that GnuCash is a large body of code written in C and Scheme (see Developing GNUCash: Source Code Overview if you want to know why). If these are languages that you are not willing to work with, consider contributing in other ways:

Examples:

• Keep this wiki up to date.
• Expand the official documentation

GnuCash help documentation and

GnuCash Tutorial and Concepts Guide.

• If you are fluent in both English and another language, help with the translation to that other language.

Q: How can I make a donation to the GnuCash project?

A: The Donation] page on the main website has information about how you can donate to the GnuCash project. We appreciate your support.

Q: What are the basics of bug reporting and enhacement requesting?

A: There are two excellent documents, which are also translated into many languages:

• How To Ask Questions The Smart Way; and
• How to Report Bugs Effectively.

You should eventually read at least one of them to avoid annoying mistakes.

But always keep in mind that the authors of these documents do not offer support for GnuCash — so you should read further on this wiki.

E.g. as GnuCash is running in different versions under different operating systems, you should usually include the information about your configuration in your request.

Q: Something bad happened; how can I help debug?

A: GnuCash has three primary ways of reporting technical detail:

1. The user interface itself with
   • a status line at the bottom of the main window,
   • tooltips, if you hover the mouse over control elements, and
   • messageboxes and similar dialogues.
2. Statements printed to the terminal from which Gnucash was run. To get this useful information on Windows or KDE or Gnome, do not run Gnucash from the Start menu. Instead call a command shell like
   • cmd.exe under Windows,
   • Konsole under KDE or
   • Terminal under Gnome from there

   and inside enter gnucash.

   • On MacOSX versions before 10.8 Mountain Lion, run GnuCash using the application icon as normal. The statements which on other systems would be sent to the terminal, on Mac OS X appear on the Console. To see them, launch Applications:Utilities:Console. On the left pane of the window, select Console Messages. The console messages appear in the right pane of the window. Scroll to the bottom. Look for a message like ....Gnucash[29751] Application Path /Applications/Gnucash.app/Contents/MacOS/Gnucash-bin. This is the first of the Gnucash terminal statements.
3. GnuCash logs most error messages to a file called gnucash.trace. Instructions for finding this file on your system may be found in Tracefile.
4. Additional in the case GnuCash crashes, experienced users might be interested in a Stack Trace. On Mac OS X, these are made automatically and may be found in Console under "Diagnostic Reports" or on 10.8 "Diagnostic and Usage Information".

Q: I think I found a bug. How do I report it?

A: First of all, try to verify that it is indeed a bug and that it has not been reported before. Search the mail list archives at gnucash-devel and gnucash-user (and gnucash-de if you speak German). Then search the Bugzilla database.

If you feel you have indeed found a bug, you can then report the bug in the Bugzilla database. Please bear in mind to report your bug as verbosely as possible. The trick here is to learn how to give the best information to the programmers about how to reproduce bugs. A Programmer will usually only be able to fix a bug they can see, if you can't make the programmer see your bug, it won't get fixed! Also see Contributing to GnuCash for additional tips.

Q: I really want feature XYZ but GnuCash doesn't have it. How do I get it added?

A: Ask nicely. :-) You can file an enhancement request at Bugzilla. Describe as clearly and completely as possible why the enhancement will be useful to a broad range of users and provide as much detail as possible about how you think it should work. You have two objectives: To sell the developers on spending their very limited time on implementing your idea and explaining to them as completely as possible what it is that you want.

Note that bit about developer's very limited time. There aren't very many developers, and there's a lot of work to do. Gnucash is maintained by volunteers working in their spare time. That means that the fastest way to get a feature added is to implement it yourself. A bug report with an attached well-written patch is more likely to get applied quickly. Please review Development#Code for details on preparing a patch.

See also: WishList

Q: When I try to browse or subscribe to the mailing lists, my browser warns me it's unsafe. What's up?

The GnuCash project uses a self-signed digital certificate to protect your access to the mailing lists site at [1]. This is necessary because the site asks you to type in your email address, and maybe a couple of other things, when you sign up. The project doesn't pay to register the digital certificate with a Certificate Authority, and as a result web browsers don't recognize the certificate and think it's unsafe.

So in summary: if your browser warns you about this site: please go ahead and enter, it's safe.

Q: In the mailing lists, how can I determine from which list the messages are being sent?

No extra tag is added to the subject line, such as [gnucash-user] or [gnucash-devel], so how can I distinguish the different lists?

A: Each message has a header "List-Id:" such as one of the following:

List-Id: General Accounting Discussions <gnucash-user.gnucash.org>
List-Id: GnuCash Software Design and Development Discussion <gnucash-devel.gnucash.org>
etc.

(To see these, look at the email source, or turn on "rich headers" or "full headers" in your email client program.) You may consistently filter off of these.

Q: Can you please configure the mailing lists so that Reply mails the list?

A: The administrators of the GnuCash mailing lists are of the belief that Reply-To munging is harmful. Please encourage the authors of Your Favorite Mail Client to respect List- headers, or train yourself to use the "Reply-To-All" command (available in every email client) when ever you want to reply to all parties; note that this works even on CC'ed / non-mailinglist email, too.

See also Reply-To Still Harmful and Reply-To Useful.

Q: Is there a version/port for Windows?

A: Yes. Starting with release 2.2.0, GnuCash is also available as a native Windows binary. See Windows for more recent details regarding the Windows port.

Other related options would be coLinux, virtualization, and a Windows-based X-server hosting a remote GnuCash session.

Q: What is the "SX" thing I see on the lists and IRC periodically?

A: SX stands for Scheduled Transaction, but Scheduled Transaction is a lot to type/write, so it's shortened to SX. Scheduled Transactions are templates for entries that will occur in the future: for example, regularly recurring bills, such as utility or mortgage payments. SX's are meant to make it easier to enter in anything that recurs on a regular basis.

Installation Troubleshooting

GnuCash 2.2.x Windows Troubleshooting

Q: When running the Online Banking Setup, I get the error message Procedure entry point "_ZN10Q3DataEditC1EP7QWidgetPKc" has not been found in the DLL "QT3Support4.dll". What's up?

A: This means you have a not-so-new version of the Qt library installed, probably one of the 4.0.x or 4.1.x series. To run the Online Banking Setup Wizard that is shipped with GnuCash, you need to install the latest version 4.3.0 and you also need to adapt your PATH environment variable so that its bin directory shows up in the PATH. See also Windows#2.2.0 only: Online Banking Setup Druid (needs Qt) .

Q: On startup I get an error message about corba-object.c and gnucash crashes. What's up?

A: We don't know yet. The full error message, we've been told, looks like this:

OTHER <> file corba-object.c: line 76 (ORBit_register_objref): assertion failed: (obj->object_key != NULL)

This is an unresolved bug so far. We can only guess this is what is being reported at http://bugzilla.gnome.org/show_bug.cgi?id=457100 http://bugzilla.gnome.org/show_bug.cgi?id=457841 ; maybe it helps to remove the directories ~/.gconf, ~/.gconfd, ~/.gnome2, and ~/.gnucash where ~ is your c:\Documents and Settings\Username directory.

Q: Can I install a new gnucash version directly on top of the older existing one?

A: Yes, you can install the newer windows binary (say, 2.2.1) directly on top of the older one (say, 2.2.0). You do not need to uninstall the older version first.

There is one exception to this rule. Several changes to the installer system were made between 2.1.5 and 2.2.0. Therefore, upgrading from 2.1.x to a 2.2.x requires an uninstall of the 2.1.x version.

Q: Why is the binary package putting all the DLLs in the gnucash folder?

A: Gnucash depends on approximately 50 other DLLs. We don't know whether any of those happen to exist already in your %windir%\system32 folder. To avoid interfering with programs depending on different versions of these DLLs, we write all the DLLs into our own folder.

"DLL hell" can be resolved by using side-by-side assemblies to keep multiple shared versions of a DLL. However, WinSXS only became available in Windows XP, while Gnucash is built for Windows 2000.

Q: Are there no further informations?

A: Yes, there is a special Windows page in the wiki. In particular you can also look in the Known Issues section on that page.

GnuCash 2.0.x Troubleshooting

Q: Why doesn't the discount from the billing terms show up when I pay an invoice?

A: Billing terms is only partially supported. The date due works but discounts don't.

Q: How do I change the register colors?

A: See https://lists.gnucash.org/pipermail/gnucash-user/2006-February/015941.html for details on using a .gtkrc file to control GTK resources, including the font and colors used in the register.

Q: Why doesn't online quoting work?

A:

1. Dependencies: You need to install the Finance::Quote (F::Q), Crypt::SSLeay, and a few other Perl modules.
2. Environment: If you are trying to add quotes from a cron job or a non-X session, you may need to enable dbus for the duration of the retrieval.
3. Currencies: If you cannot get CURRENCY only quotes since early 2012, upgrade to the newest version of Finance::Quote.
4. A Service Change: Finance::Quote works by querying financial web sites. A few of them provide CSV output, but most have to be screen scraped. In either case the web sites can change and they never tell us about it, users do. The first thing to do when F::Q has been working and stops is to check CPAN for a recent update, and to install it if there is one. That link is a search, and Finance::Quote will be the first hit; the latest version number and release date are under the name. If you already have that version installed, file a bug with Finance::Quote or report the problem on the GnuCash-user mailing list.

Windows Users: Note that recent versions of Finance::Quote require more recent versions of perl on Windows. If you encounter trouble with the installation, remove whichever perl you have, both with Control Panel and Windows Explorer, then run Install Online Price Retrieval, which will install a recent version of Strawberry Perl for you. N.B. you don't necessarily want to do that if you're using perl for other purposes, but in that case you probably already know how to upgrade perl.

To determine the version of Finance::Quote you have installed: Open a command/terminal window and run gnc-fq-check (C:\"Program Files (x86)\gnucash\bin\gnc-fq-check" on Windows). The first number in the result list is the Finance::Quote version.

Q: I use KDE and tried the gnucash Gnome2 port, but my fonts look ugly

A: The GNOME-2 port uses your GNOME font settings. You probably just need to change (or create) your gconf settings for GNOME-2. This can be done from KDE by running gnome-control-center from a konsole command line (or by using the Alt-F2 run command dialog).

Q: Running 2.0.x on Debian/Ubuntu crashes with "no code for module (g-wrap gw standard)". What does this mean?

A: GnuCash uses g-wrap to interface between C and Guile. Debian/Ubuntu have packaged g-wrap in such a way that the runtime files are separated from the development files, and don't have an explicit dependency on the runtime files. If you get this error, it means you do not have the g-wrap runtime package installed. You should install the package named guile-g-wrap and then gnucash should run. See http://bugzilla.gnome.org/show_bug.cgi?id=330560

The exact error message when the startup crashes is this:

<unnamed port>: In procedure scm-error in expression (scm-error (quote misc-error) #f ...):
<unnamed port>: no code for module (g-wrap gw standard)

Q: What does it mean when GnuCash (built with g-wrap-1.9.7) crashes with an error about a wrong type of argument in hook-run-danglers-real?

A: There is a bug in g-wrap-1.9.7 that causes this. You need to remove g-wrap 1.9.7, install g-wrap 1.9.6, and then rebuild GnuCash. Then this error will go away.

The exact error message at the end of the stack trace when the startup crashes is this:

In /usr/share/gnucash/scm/hooks.scm:
 22: 3  [gnc:hook-run-danglers-real "hook_report" #f]
 
.../hooks.scm:22:3: In procedure gnc:hook-run-danglers-real in expression (gnc:hook-run-danglers-real hook args):
.../hooks.scm:22:3: Wrong type argument in position 2: #f

Q: What happened to my Profit and Loss report when I upgraded to 2.0?

A: The "Profit and Loss" (or P&L) report was renamed to the "Income Statement". So just run an Income Statement report and you'll get the report that you want.

Q: I downgraded from GnuCash 2.2 to 2.0; what's up with this ROOT account?

A: The Root account is an internal change in the 2.2 code, introduced by the removal of the AccountGroup data structure. (Accounts are now their own grouping construct, but we still need a top-level "Root" account to take the place of the old top-level AccountGroup.)

If you're planning on sticking with your 2.0 install for a while, then you can re-parent each child of the "Root" Account to be a top-level account, then remove the Root account. If you're planning on using the same datafile between a 2.0.{<5} and 2.2 installation, every time you open the datafile with 2.2, the Root account will be re-inserted.

• NOTE: Make sure if you do downgrade from 2.2 to 2.0 that you re-parent all your accounts. Failing to do so will cause problems when you upgrade back to 2.2. Many things in 2.0 won't work until you re-parent accounts to top-level accounts.

RPM-based GnuCash versions

Q: Are there no (more recent) precompiled rpms for my distro?

A: Not here, but you can use the search at http://rpm.pbone.net/ with a search string like "gnucash-2.2".

Macintosh OS X

Q: How to install on Mac OS X?

A: Download the dmg from the links at the top of GnuCash page or visit MacOSXInstallation for more detailed instructions and alternatives.

A2: See also: http://homepage.mac.com/elliottmce/gnucash_guide/

Q: I installed from the DMG download and the Help menu doesn't work. How do I install the documentation?

A: It's already installed, but the Help menu relies on a Gnome program (Yelp) that isn't available to the Gnucash.app bundle — not even if you install it from Macports. Open Gnucash.app/Contents/Resources/English.lproj/GnuCash Help/help.html or Gnucash.app/Contents/Resources/English.lproj/GnuCash Guide/index.html in your browser. For example, control-click on Gnucash.app and select "Show Pacakge Contents" from the context menu, navigate to Contents:Resources:English.lproj:Gnucash Help and double-click help.html.

Q: I installed from the DMG and I get an error about a path "not found"

A: You've probably dragged Gnucash.app to a folder whose name has a space in it (or some parent folder does). GnuCash's launcher script is a mix of shell and Apple Script, and at present it chokes on spaces in pathnames. Move Gnucash.app to a folder with no spaces (Applications is traditional) and all should be well.

Q: I just installed GnuCash and all the labels are in Japanese

A: It's usually caused by something being not-quite-right in the language defaults on your Mac. Open System Preferences>Languages & Text (Snow Leopard) or International (Leopard and Tiger) and change the order of the languages, close system prefs, then repeat and change it back to the way you like it. Try GnuCash again.

Q: I tried to print a report, but there aren't any printers in the print dialog

A: This will be fixed in 2.3.12; in the meantime, use the "Preview" button, which will open a PDF of the report in whatever is your chosen PDF viewer (Preview.app by default); you can print from there.

Q: I want to remove GnuCash from my Mac. How do I do it?

A: Note: These instructions apply to the stand-alone download hosted on GnuCash's SourceForge project. Users of MacPorts or Fink should consult the instructions for those distributions.

Almost all of it is contained in the application bundle, Gnucash.app, which you can just drag to the trash. If you're using Gnucash 2.3.9 or later, Gnucash's configuration files are in $HOME/Library/Application Support/Gnucash, which you can also drag to the trash. If Gnucash has ever crashed, there may be crash logs in $HOME/Library/Logs/CrashReporter/ that you'll also want to drag to the trash. CrashReporter log filenames start with the name of the application, so the Gnucash ones will start with "Gnucash".

If Finder won't let you drag Gnucash.app to the trash, it's likely that there is one or more instances of dbus-daemon (a Gtk inter-process communication program) still running. There are a couple of ways to stop them:

* The simpler if you're comfortable with the command line is to open /Applications/Utililities/Terminal and issue the co mmand "killall dbus-daemon".

* Otherwise, open /Applications/Utilities/Activity Monitor and type "dbus" into the filter window in the upper right hand corner. That will restrict the list to only instances of dbus. Select each in turn and click on the red octagon "Quit Process" tool on the left end of the toolbar and select Quit on the ensuing dialog box.

There may be other configuration files in hidden folders in your home directory which you'll have to delete from a Terminal command line. Those directories are:

* .gnucash (if you've used an older version of Gnucash)

* .gconf

* .gconfd

* .gnome2

* .gnome2_private

* .banking (if you've used the online banking features with an older version of Gnucash)

* .aqbanking (if you've used the online banking features with Gnucash 2.3.9 or later)

To delete these directories, open Applications:Utilities:Terminal and at the prompt enter

rm -rf dirname

for each of those directories.

Gnucash created a symlink pointing to itself when you first launched it. It's either /opt/gnucash-2.2.9, /opt/gnucash-2.3.x, or /Library/Gnucash-2.3.x. The last can be dragged to the trash from Finder (you might have to authenticate as an administrator). The other two must be deleted from a command line, e.g.:

sudo rm /opt/gnucash-2.2.9

Sudo will request your password, and you must be logged in as an administrative user. Look in System Preferences > Users (Tiger and Leopard) or System Preferences > Accounts (Snow Leopard. For each account, there's a checkbox named "Allow user to administer this computer" — that must be checked for the account to which you are logged in.)

Your account files are where ever you put them. There will be corresponding backup and log (suffix .log) files which start with the same name as your account file. You can drag the lot of them to the trash as well.

Q: How do I install Finance::Quote on a Mac?

A:

You must be logged in to an account "authorized to administer this computer" in order to install Finance::Quote.

1. Install Xcode.app, a free download from the App Store or, on pre-10.7 versions of OSX, included with your distribution DVD.
2. (App Store downloads only) Run Xcode, open preferences, select downloads/components, and install command line tools.
3. Drag Update Finance Quote.app to the same folder that you put Gnucash.app, then double-click it to open. It will open a Terminal window, request your password for root access, and run cpan to install Finance::Quote from the perl software site CPAN. It will ask for confirmation many times; accept the default every time.

Note: After the Date::Manip update of 31Oct2012, many Mac users have had problems with the installation being corrupted and failing. The symptom is the following error message:

 Bareword found where operator expected at ./Makefile.PL line 1, near "30 mtime"
 	(Missing operator before mtime?)
 Number found where operator expected at ./Makefile.PL line 2, near "30"
 	(Missing semicolon on previous line?)
 Bareword found where operator expected at ./Makefile.PL line 2, near "30 atime"
 	(Missing operator before atime?)
 Number found where operator expected at ./Makefile.PL line 3, near "30"
 	(Missing semicolon on previous line?)
 Bareword found where operator expected at ./Makefile.PL line 3, near "30 ctime"
 	(Missing operator before ctime?)
 ERROR from evaluation of /Users/john/.cpan/build/SBECK-DklzIi/Date-Manip-6.36/Makefile.PL: ERROR from  evaluation of /Users/john/.cpan/build/SBECK-DklzIi/Date-Manip-6.36/PaxHeaders.11917/Makefile.PL: syntax error at ./Makefile.PL line 1, near "30 mtime"
 Warning: No success on command[/usr/bin/perl Makefile.PL]

There are two ways to work around this problem. Both require that work with the command-line shell in Terminal. Note that the first invocation of `sudo` will prompt for your password, and that you must be logged in to an account "authorized to administer this computer".

Method 1:

 1. cd ~/.cpan/build/SBECK* (The full name of this directory will be different on each system)
 2. sudo rm -rf Date-Manip-6.36/PaxHeaders.11917
 3. cd 
 4. sudo cpan -i Date::Manip

Method 2:

 1. sudo cpan -i CPAN
 2. sudo rm -rf ~/.cpan/build/SBECK*

After which you can re-run Update Finance Quote and it should work.

See also: Online Quotes

Microsoft Windows

Q: Gnucash crashes immediately on startup

A: This can happen for a variety of reasons.

One that pops up from time to time and is quite hard to detect unless one knows to look is having Lilypond installed. Lilypond for Microsoft Windows is built with a different version of Guile than is Gnucash, and the Lilypond installer insists on placing its path in the global path list in such a way that Gnucash finds Lilypond's Guile instead of its own, and crashes. The solution is to remove Lilypond's directory from the global path in control panel and add it to the environment settings in the Start Menu and Desktop aliases.

All GnuCash versions

Q: Why does GnuCash start incredibly slowly on a FreeBSD system?

A: Your copy of GnuCash wasn't compiled correctly for FreeBSD. When you compile gnucash on FreeBSD you need to set "libltdl_cv_sys_dlopen_deplibs=yes" in the environment before running the ./configure command.

Q: Why does GnuCash run incredibly slowly on a Unix system using X?

A: Please verify that the RENDER option is not disabled in your X configuration. Sometimes this is done for debugging purposes, like so:

  Section "Extensions"
    Option "RENDER" "off"
  EndSection

Q: How do I fix a system error when getting stock quotes?

A: Try the steps below. After each step, run gnucash and see if that solution resolved the problem of retrieving stock quotes.

1. Make sure you're running Finance::Quote 1.20 version or later. Earlier versions can no longer retrieve quotes from Yahoo.
2. Run the command gnc-fq-check from the command line. The output should return the F::Q version and the available sources and look like ("1.20" "fool" "nasdaq" ...). If it doesn't, follow the directions to install any missing libraries.
3. Run a command of the form gnc-fq-dump -v <source> <symbol> from the command line.

   You can get the exchange rate between currencies aaa and bbb with aaabbb=X at Yahoo, e.g.:

   gnc-fq-dump -v yahoo USDEUR=X.

4. If the output of the last command seems ok but Gnucash still fails to get the quote run the command echo '(yahoo "CSCO")' | gnc-fq-helper from the command line. You should get something that looks like (("CSCO" (symbol . "CSCO") ..... (currency . "USD"))). There you can also find bad things like trailing blanks. If you get an error message about a missing file instead, that's your problem. This is a dependency that gnucash doesn't know about and so doesn't check for it. You will need to satisfy the missing dependency.

   But usually, at least under linux, it helps to run gnc-fq-update as root.

   For Windows you should probably look at Windows#Finance::Quote_Problems_with_Windows_.28VISTA_32-Bit_SP1.29.

5. Run gnucash from the command line with the -debug argument, attempt a quote retrieval, and then contact the developers either via email or on IRC.
6. Sometimes it might help to know what module Perl does actually load.

This command will tell you exactly that for e.g. Tiaacref:

perldoc -lm Finance::Quote::Tiaacref

See also: Online Quotes

Q: I'm running Debian/unstable, just upgraded, and GnuCash no longer works. How can I fix that?

A: Contact Debian. Read the gnucash-user archives because someone else probably already reported the problem.

Examples:

If you get an error about gncownercreate, see https://lists.gnucash.org/pipermail/gnucash-user/2004-March/009864.html

If you get an error about format not being found, see https://lists.gnucash.org/pipermail/gnucash-user/2004-March/009676.html

If you get an error about "Unbound variable: gnc:menuname-ncreports", it should be fixed in version 1.8.12-5. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348502

Q: GnuCash crashes when I try to run it in a non-UTF‐8 locale

A: This is actually a bug in Gtk+ a shared library used by GnuCash, and not a bug in GnuCash itself. If you encounter this problem, you should contact your distribution and ask for a Gtk+ update. You can refer the Gtk+ maintainer to the following related bug reports if he's not aware of the cause of this problem:

• [Bug report in the gnucash bug database]
• [Bug report in the debian bug database]

Q: Why do you have to depend on Gnome? It's so bloated!

A: GnuCash uses specific Gnome libraries for the following features:

• printing (gnomeprint)
• configuration storage (gconf)
• graphing (goffice)
• UI support (libgnomeui)
• HTML rendering (gtkhtml)
• Help (yelp)

We do this because we'd rather focus our energy on building an accounting system than a printing library, graphing library, html-rendering library... it's just the reasonable way to build software, and has been for years.

There's no requirement that you use the full-blown Gnome desktop environment, or run Metacity as your window manager, or that you launch GnuCash only from the GNOME panel, or anything like that. We just need the libraries. Many users run GnuCash just fine from their KDE, XFCE or even TWM desktops.

As for complaints about how "bloated" Gnome (and KDE and...) are, it's hard to believe a system in which every app re-implemented their own support for common tasks (such as printing, help-browsing, &c.) would ultimately be less bloated.

Q: I'm having trouble getting GnuCash running on Slackware

A: See http://rjmarq.org/gnucash.html and http://www.slackages.com/linux/slackages/index.html

Q: GnuCash crashes on startup trying to run an SX. How do I fix this?

A: We're still trying to track down all the various SX problems. First, you should make sure you're running the most recent release. Second, if you're running the most recent release and still having problems you should file a bug report with all the output on your terminal (you ARE running gnucash from a terminal, RIGHT???). Third, you should backup your data file because the developers may want to see portions of it to help track down this problem. Finally, run:

gnucash --nofile

then turn off the AutoRun option from Edit -> Preferences -> Scheduled Transactions . Then exit and restart GnuCash and it should open your data file just fine.

Q: GnuCash crashes when I run a Custom Report saying something about a Stack Overflow. What does this mean?

Note 

This problem no longer happens as of GnuCash 2.0.

A: There is a problem with the Save Report feature when you save the report settings for a report with the same name as a default report. This problem manifests itself as a recursive execution and causes the program to crash. To keep yourself from hitting this bug, make sure you always change the name of a report before you try to "Save Report". To change the report name click the "Options" button in the toolbar. Note that the "Save Report" button really means "Save Report Options" or "Make Into Custom Report".

If you get into this situation the easiest way to get back a working system is to delete your saved reports:

• Exit gnucash
• Delete the file ~/.gnucash/saved-reports-1.8* (or ~/.gnucash/saved-reports-2.* if you run a more recent version)
• Restart gnucash

If you do not want to lose all your saved reports, you can edit the saved-reports-* file and remove the corrupt report entry. Locate the problem report definition, and delete the entire section, which begins with a line of semicolons (";") and continues until the next occurrence of a line of semicolons. If GnuCash will not load your file after deleting a report (i.e., it begins to load but crashes while setting up the screen), you will have to edit the file in ~/.gnucash/books/{yourfile} so that GnuCash doesn't attempt to open the missing report. This file has entries for each tab to open on startup. Each tab is headed with "[Page x]"; removing an entry prevents it from loading on startup.

This is a known bug. For more information see http://bugzilla.gnome.org/show_bug.cgi?id=168250

Q: I'm trying to read the tutorial/help but it says that it's unable to find the url. What's up with that?

A1: You don't have the gnucash-docs package installed. Install that to the same prefix where you installed gnucash and the docs/tutorial will show up properly.

If your default Desktop is not Gnome, you may also need to install yelp.

A2: You ran in an "really stable" [open]SuSE bug.

GnuCash Files and managing a GnuCash installation

Basics: Filenames, Directories, ...

Q: What's the gnucash file extension?

2.2.x and earlier

GnuCash does not enforce any particular file naming convention or extension. However, the following extensions are described in the "shared-mime-info" package used by almost every distro and desktop environment to associate applications with files. Naming your datafile with one of these extensions will allow the gnucash to be opened when a file is seen and activated in a file browser.

• .xac (short for "X-Accountant", the predecessor of GnuCash), still in use for your backup files,
• .gnc (the "internal" three-letter-abbreviation of GnuCash)
• .gnucash (recommended and the only one that works on Windows)

2.3.15+ and 2.4.x

Starting with GnuCash 2.3.15, .gnucash is enforced as file extension for new files. Existing filenames will not be changed though and the old extensions are still recognized on most systems.

Q: Where is my GnuCash data file?

A: If you are using

• postgres or
• mysql,

there is no data file but a database in your DBMS - for a backup read the manual of your DBMS - ,

• the default xml format, or
• the sqlite format,

the data file is called something.gnucash, where something is the name you specified when you first saved the file.

See the previous question if you are using an version 2.2.X (or older) of GnuCash and need to figure out the data filename extension (details on XML format).

To figure out where the file is, open up GnuCash and note down the name of the file that appears in the title bar. Then, click File > Save As…, and note down which folder the Save As… dialog box opens in. That is the folder your data file is located. Then, cancel the Save As... dialog box.

If the history got lost, search your disk for directories containing .gnucash or .xac and .log files.

Some adjustments can be done using Environment Variables and User Configuration Files.

Q: How do I backup my data?

A:It depends.

• If you're using the XML (default) backend, GnuCash makes local backups for you every time it saves your file. It does this by renaming the previous version of the file with a date-time-stamp and a new .gnucash suffix. For example, if your data file is named MyAccounts.gnucash, one of the backups might be named MyAccounts.gnucash.20140131150812.gnucash.
• If you're using the SQLite3 backend you should use a timed backup program to copy your account file in some way.
• If you're using either the MySQL or Postgresql backend, you should perform backups on the database in accordance with the recommended best practices appropriate to the server. We're not competent to advise you about this beyond recommending that you make backups.
• We strongly recommend that whatever backup plan you use includes a provision for offsite backups. A good option is one of the many internet storage facilities like DropBox, Google Drive, or Carbonite. Those are just popular examples; there are dozens of such services, and we can make no recommendation of one over another.
• Restoring is simply a matter of removing the defective MyAccounts.gnucash and renaming one of the backup files to that, then starting Gnucash or using File>MyAccounts or File>Open and selecting MyAccounts.gnucash from the File Chooser.
• To restore from an off-disk backup, just copy MyAccounts.gnucash back into the directory where the original is.

Q: How do I backup my GC environment, including preferences?

A: At first you should save your actual GnuCash ledger file. It is up to you if you wish to save the backup and log files .gnucash or .xac, .log (see gnucash file extension). For your preferences you need also to save

• $HOME/.gnucash - most of your preferences, adjusted report settings, ...
  • or $HOME/Library/Application Support/Gnucash under MacOS X,
• $HOME/.gconf/apps/gnucash/ - the visual settings like column width, history, ...

Before the usage of GConf that settings were stored in

• $HOME/.gnome/GnuCash and
• $HOME/.gnome/accels/GnuCash.

• $HOME/.[aq]banking - if you are using the AqBanking online banking. In older versions it was named .banking but .aqbanking is the current name.

Microsoft Windows Note: $HOME is at %SYSDRIVE%\Documents and Settings\%USER%\. For example, if your system is :installed on C: and your username is "foo", $HOME is C:\Documents and Settings\foo, and you'll find your gnucash config :directory at C:\Documents and Settings\foo\.gnucash.

Q: What are all these .gnucash and .log files filling up my directory?

A: These are backup data files (".gnucash"; it was ".xac" in versions before 2.4) and log files (".log") that GnuCash creates to prevent data loss. Gnucash will remove them after a configurable amount of time (Preferences/General/"Days to retain log files"). In the normal case when your data file is ok and you don't need old versions of the file, you can remove these files safely.

You should notice that the backup and log files have a format of <name>.YYYYMMDDHHMMSS.gnucash (or .log). These are backup (and log) files from your data file, <name>.

Q: Why is my file name getting longer and longer?

A: GnuCash creates a backup file by taking the current data file and adding the date/time to the end (YYYYMMDDHHMMSS.gnucash). Older versions up to 2.3.x still used the form YYYYMMDDHHMMSS.xac - from GnuCash's ancestor XAccountant. So if you're using a file named "Foo.gnucash", then you'll get backups of the form:

Foo.gnucash.20100719100214.gnucash

Now assume that instead of opening "Foo.gnucash" you open one of these backup files, you make changes to it and then save the file.

For starters, this means you've just over-written the original backup file which is always a bad idea. Backups should never be changed.

Secondly since you saved changes, GnuCash will create a backup file based the file you just changed using the same naming system: it adds a date/time extension. Since the file you saved already had such an extension, you end up with a backup file named:

Foo.gnucash.20100719100214.gnucash.20100719112352.gnucash

Repeating this process will add to the file name until it exceeds the operating system limits.

The fix:

1) Don't open a backup file

1a) If you DO open a backup file, never simply save it out again, instead use Save As to give it a new name.

2) Make sure you're always using your base data file

3) If your base data file for some reason is bad, and you need to recover from a previous backup file, copy the backup file over your bad base file, for example:

cp Foo.gnucash.20100719100214.gnucash.20100719112352.gnucash Foo.gnucash

and then File -> Open the new file, Foo.gnucash.

Q: Gnucash crashed and lost a bunch of my edits. How do I recover them?

A: First, read the previous two FAQs about backup and logfiles.

The first thing to check is that you are, in fact, opening the right file. Look up in the title bar: If it has a long string of numbers starting e.g. 20111011 (2011-10-11, i.e., 11 October 2011) then you've opened the wrong file. If you haven't done this too many times, the right one should still be in the recent list in the File menu. Open it and make sure that you really have lost work.

If you're sure that you got the right file and that your work is still missing, look at the log files for that data file -- and for any backup files you might have entered data into (Those will have logfiles with names that look like filename.timestamp.gnucash.timestamp.log). Quicklook works on log files, so you can browse the log files in Finder. Find the earliest one for which data does not appear in your data file and select File>Import>Replay Gnucash .log File, then select that log file. Repeat for every subsequent log file.

Click the save button.

Go back to work.

Warning: The log file will not replay business actions. So if you posted invoices or processed payments or did anything else with the business functions, replaying the log will destroy your data! Do not replay a log that has transactions from business feature operations or internal data structures will be completely messed up and you will have lots of trouble cleaning up later.

If you did lose business feature work the only thing you can do is redo the work by hand and then make sure you click save.

Save early, save often.

Q: GnuCash says that it can't obtain the lock for my file. What should I do?

A:' There are two ways to get that message: One is to have another instance of GnuCash running with the same file or database open. If you're using MySQL or Postgresql, or if you have your file in a service like Dropbox, the other instance might not be on the same computer. The other way is if GnuCash didn't shut down correctly the last time it quit, and so didn't remove the lock.

• If you're absolutely sure that another instance of GnuCash doesn't have the same file open, click on "Open Anyway".
• Otherwise, select one of the other buttons.

Q: I moved/renamed my data file and my reports disappeared. How do I get them back?

A: Reports are stored in a separate file in the ~/.gnucash/books directory. File name is a url-encoded path name for the main data file. To get your reports back, copy old report file over the new reports file, then open ~/.gnome/GnuCash in your favorite editor and copy section corresponding to the old file to the section of the new file

Q: Why can't GnuCash find my data file anymore? It just says: parser error : Start tag expected, '<' not found

A: We're very sorry, but you just shot yourself in the foot. GnuCash uses $HOME/.gnucash to store metadata files. In particular, $HOME/.gnucash/books stores metadata about your data files. In versions 1.8 and earlier the metadata file was named as the encoded name of the full path to your datafile, but as of 2.0 this was changed and the metadata file is just named the same as the data file. So if you saved your data file into $HOME/.gnucash/books and updated your versions, GnuCash just overwrote your data file with the metadata file. You'll need to copy a backup file and move it somewhere outside of $HOME/.gnucash and tell GnuCash to look there by using the File -> Open feature to load the new datafile.

Note: This should no longer happen as someday [in 2011?] the metafiles got the extension .gcm GnuCash Metafile, while by default datafiles get .gnucash. Nevertheless it is a bad idea to store your datafile in this application settings folder.

Q: I have deleted a gnucash file from my computer. How can I remove that file from the File menu's short list as well ?

A: The list of files you see in the File menu is the list of recently used files. Strictly speaking the items in this list are still "recently used" even if you deleted the file from your computer in the meantime (you won't be able to open it anymore from the File menu). So it's really only a cosmetic issue. But if it bothers you enough and you really want the obsolete entries removed, please read on.

The list of recently used files is stored in an independent preferences database called GConf. GnuCash doesn't have a direct way to edit this. Depending on your operating systems there are different ways to alter them:

Linux and similar You can use a tool called gconf-editor to manipulate GConf. You may need to install it using your distribution's software management system first. Then open the GConf Editor gui tool, and use it to modify the /apps/gnucash/history tree.

Windows On Windows the gconf editor tool is not available. Here you will have to hand edit the gconf files using a text editor while GnuCash or other Gnome based programs are not running. The file you will want to change is normally c:\Documents and Settings\<user>\.gconf\apps\gnucash\history\%gconf.xml (Windows XP) or c:\Users\<user>\.gconf\apps\gnucash\history\%gconf.xml (Windows 7). This file is in xml.

Mac OS X As with Windows gconf editor is not available on this platform and you will have to hand edit the gconf files using a text editor while GnuCash or other Gnome based programs are not running. The file you will want to change is ~/.gconf/apps/gnucash/history/%gconf.xml. This file is in xml.

GnuCash Localization (L10n) and Font Issues

Q: I want to use GnuCash in my own language

A: The answer moved to Locale_Settings.

Q: I want to use GnuCash in a different language than my monetary/decimal separator

A: Then you want to set the LC_MONETARY envrionment variable different from the LANG: "env LC_MONETARY=fr_FR".

Q: I'm a Mac user and I want to use Gnucash in a language different from my system settings.

A: See the Wiki Article on OSX Locale Settings.

Q: How get I rid of strange unreadable characters or adjust the font size

A: You need a font in which the respective characters are defined. Your system tools usually offer some font viewer to test them. Then adjust the fonts for

GnuCash reports: under Edit->Stylesheets adjust them for all your used stylesheets.

GnuCash user interface: You need to adjust the GTK settings:

Linux: The easiest way is to use the Gnome Control Center.

MacOs: Create a file

X Window version: ~/.gtkrc-2.0

native version: ~/.gtkrc-2.0.gnucash

with the following contents:

style "font"
{
  font_name = "Arial Narrow 12"
}
widget_class "*" style "font"
gtk-font-name = "Arial Narrow 12”

Substitute any font in FontBook for “Arial Narrow 12”.

Q: I dislike some of the new currency symbols of GnuCash 2.6

A: If you really know a symbol is wrong or outdated,

follow #Q: I think I found a bug. How do I report it? and file it against the component Currency and Commodity.

Don't forget to add a link to a reliable source like wikipedia or your central bank.

In between and otherwise:

Tools->Security editor

checkmark Show national currencies,

open the CURRENCY tree,

search the ISO symbol of that currency and click edit,

replace Display Symbol with your desired text

and confirm it by clicking OK.

Using Different Versions, Up- And Downgrade

Q: Can I exchange Gnucash file with any other version of GnuCash?

A: Not quite.

• You can always upgrade from versions >= 1.8 to a higher release. In most cases you can go back-and-forth between adjacent major releases:
• You can read 2.0 in 1.8.x fine.
• Reading 2.2 in 2.0 will not work, if you have scheduled transactions.
• 2.4 and 2.2 files are interchangeable
• 2.6 and 2.4 files are interchangeable unless you use the Credit Notes feature in 2.6

Q: Can a new GnuCash release still read my old data file?

A: The answer depends on how much forward you want to go.

Minor releases 

GnuCash maintains full compatibility between minor releases. So a file you have created with 2.2.5 will work with 2.2.9 and the other way around.

Major releases 

The data format between major release can change. However, the GnuCash developers try very hard to be as compatible as possible. Each major series is normally at least compatible with the previous major series. So if you have a data file created with GnuCash 2.0.3, you should be able to open this with for example 2.2.5. Skipping a major release may cause issues though.

You can skip major releases by doing the conversion in two steps. Suppose you want to jump from version 1.8.12 to 2.2.9. To do so, you should first open the file with a GnuCash 2.0.x release, save it from within 2.0.x and then open the saved file in 2.2.9.

Important 

When moving from one major release to another, you are best to run "Check & Repair" when opening the file for the first time in the new release. Specifically when running it after moving to a new major release, it may deal with data format issues the old release ignored, but the new release has problems with (like for example bug #340372.

Unstable releases 

The unstable (or development) releases can make improvements to the data format or provide new data formats altogether (like storing gnucash data into a database). For unstable releases, compatibility is not guaranteed, not even between minor releases. (Such an incompatibility was introduced for example in the new database backend between development releases 2.3.3 and 2.3.4.) The reason is simple, these releases are to test new functionality, not for long term production use. You should therefore only use development releases on copies of your data or on separate test data.

Q: And the other way around ? Can an old GnuCash release read a data file created with a new release?

A: Here as well, the answer depends on how far apart your releases are.

Minor releases 

Again, GnuCash maintains full compatibility between minor releases. So a file you have created with 2.2.9 will work with 2.2.5 and the other way around.

Major releases 

This is trickier. In general here as well, GnuCash tries to be at least backwards compatible with its previous major release, although this may not always work. Here are some of the potential problems

• If new functionality results in new fields in the data file, these new fields will not be visible in the old release. Depending on how these fields were added, this would cause your data file to be unreadable by the old release or the new fields will simply be ignored (but retained !). Obviously the latter is the preferred solution as it keeps backward compatibility. But it may technically not be possible to implement the new fields that way.
• For example, the new scheduled transaction system in 2.2 breaks compatibility with 2.0. If you don't use scheduled transactions in GnuCash 2.2.x, you can use your data file in 2.0.x as well. But that's not possible if you do use scheduled transactions.
• The upcoming 2.4 release will introduce several new ways to store data (in databases). Obviously, if you store your data in such a new format, you won't be able to read this in earlier GnuCash series. But the 2.4 series also still supports the xml format of the previous releases. If you want to use a datafile in both 2.4 and older releases, you will have to use this xml format.

Multiple Computers, Users, ...

Q: Can I use GnuCash with multiple users? Maybe via the SQL backend?

A: That depends on what you mean exactly. You can share your data file with others, for example by storing it on a network mounted drive. Note that this will enforce serialized, exclusive access to the data file and editing; there is no real support for simultaneous editing. File-locking is employed on this file, so it should be NFS-safe. SMB-safe locking is unknown.

Even the dbi (SQL) backend which comes with GnuCash 2.4 is currently not designed for true multi-user access. Trying to work with multiple users at the same time in the same database will be prevented by means of a locking mechanism. Circumventing that can cause data loss. You can however share the database with different users, provided you ensure serialized, exclusive access. In other words, only one user at the time should have GnuCash open with that database. Once this users closes his GnuCash session, another user can start GnuCash on this database.

Q: I'm running GnuCash under GNU/Linux. Can I give another user access to my GnuCash files?

A: Yes, as long as both of you do not access them at the same time. You do it the same way you'd share files of any type under Linux: put them in a folder that both of you have access to, and change the permissions so that you both can read from and write to the files. You really don't want more than one person to have them open for editing at the same time, however, as whoever saves last will overwrite the changes of whoever saves first.

Q: I use the same account on multiple computers (through a repository), how do I also transfer the reports I currently have open?

A: Copy all of $HOME/.gnucash and $HOME/.gnome/GnuCash. Alternatively, from 1.8.10 onwards you can "save a report", which will be saved in $HOME/.gnucash/saved-reports-2.0 . If you copy that file to your other computer, you will have the same reports available.

SQL Database

Q: Is there a database backend?

A: An abstraction layer has been created using first GDA but then replaced with DBI, which has proved to work well.

This is the first step in making GnuCash suitable for simultaneous multiuser use. Until this is complete almost all users are better off with the XML backend.

Q: Should I use the XML or database backend?

A: Until GnuCash supports simultaneous multiuser use almost all users are better off with the XML backend.

Q: Is the Postgres DB / SQL backend supported?

A: GnuCash versions 2.4 and later release support SQL via the DBI backend. It supports PostgreSQL, MySQL and SQLite3 databases.

Previous GnuCash releases contained a PostgreSQL specific backend which was introduced in GnuCash 1.6. This backend however didn't support the business functions and in general hasn't been maintained since. It has been removed for 2.4.

Some history:

The PostgreSQL backend was introduced in the 1.6 code line, but it never supported any features introduced since the 1.6 release, especially the Business features and Scheduled Transactions. Even so, modulo those features, the Postgres backend should still basically function, even in the 2.2 release. However, since the 2.0 release, some user-interface elements relating to using the Postgres backend are no longer available; use a postgres:// url from the command-line to access it.

In 2006, work started to create a GDA-based backend to replace the Postgres-specific backend. The GDA backend was replaced with a DBI backend as of 2Q 2008. This DBI backend is what eventually has been released with GnuCash 2.4 late December 2010.

The Postgres backend has been considered obsolete by the core developers since the 2.0 release and has been removed from the 2.4 release.

Q: Can I open my GnuCash SQL database with another program, perhaps Microsoft Access?

A: A qualified yes. To use a PC program like Access (or Open Office's Database) you'll need the ODBC driver for whichever database you decided to use. You can of course query the database using the tools that database engine (SQLite3, MySQL, or PostgreSQL) provides, including embedded sql programming tools.

Qualified, though, because the relation information isn't encoded in the database: there aren't any foreign keys defined at present. All of the relations are established in C or Scheme code in the GnuCash libraries. What's more, there's a lot of data stored in a single "key/value" table which has relations to almost every other table in the database. Because of these limitations, we insist that you must not write to the GnuCash database except through the GnuCash libraries.

The table layouts are documented at SQL

Q: Opening an sqlite3 datafile which is on a smb network drive crashes GnuCash

Q: Saving to sqlite3 on a smb network drive gives locking errors

A: It seems some smb servers don't deal well with the low level file locking required by sqlite3. It was experienced when the sqlite3 file resided on a Windows XP machine and accessed from a linux machine that mounted the Windows drive via cifs. It is very likely OS X clients will run into the same issue.

There is a way to solve this (at least on linux): if you mount your Windows drive, add the option "nobrl" to the mount command (or in /etc/fstab). This will disable the offending low level locking mechanism. You should be aware though that this will risk file corruption if two users are using this data file at the same time. Since GnuCash doesn't support multiuser, simultaneous access anyway, this shouldn't be a problem though.

For further details about this problem, you can check these links:

1. GnuCash bug 637886 and particularly comment 20 which summarizes the issue
2. Samba bug 5994, which seems to lie at the core of the issue.

Q: I tried to start up GnuCash 2.4.1 on my SQL database and I got an error about libdbi and large numbers

A: Libdbi is a library that we use to generalize access to the SQL databases we support. Unfortunately the default way to compile it doesn't agree with some compilers, resulting in its inability to work with large numbers... the large numbers that we use to store amounts. That means that you'll lose a lot of data if you try to use a SQL backend with the library in place. We've encountered several Linux distributions that have the buggy libdbi, so we inserted a test into Gnucash to catch it. You can read the bug report for technical details, but if this happens to you, you should file a bug report with your distribution. If you're able to build programs, you can build your own libdbi with different parameters to avoid the bug (again, details are in the bug report). Otherwise, you'll have to use the XML backend.

Security: Encryption, Password Feature, ...

Q: Is it possible to provide security for GC data using CFS, etc.?

Q: "Can you please add a password feature?"

A: The core developers – which includes those with long-term experience with well-known names/brands in computer security – believe that each app should do one thing well, and leave other concerns to other apps. Especially "tricky", critical concerns like data security. In this case, GnuCash would do a poor job of being a good security application. You're encouraged to use an encrypted file system to store your critical data files — GnuCash and others.

Encrypted filesystem options:

• Loop-AES. See Example 7.3 in particular for setting up an encrypted specifically-mountable loopback partition.
• EncFS
• See gnucash-devel thread. Note that the link in the post does not work, but this one does: crypto.com.
• CFS is fairly old code, and has some flakiness, but does work with modern systems (e.g., see pkgsrc/security/cfs in NetBSD's pkgsrc).
• NetBSD's cgd(4), which is a cryptographic layer for an entire block device
• FreeBSD's geom-based encryption
• TCFS
• TrueCrypt, multi-platform open source encrypted block device

Other Solutions:

• Based on GnuPG and a script are Syncencrypt windows construction and Syncencrypt linux construction‎.

Note that if you use the online banking features within GnuCash, you should be aware that your account numbers and user IDs are stored in plain text in your AqBanking settings, which are stored in

• ~/.banking/settings.conf for old aqbanking versions and somehwere in
• ~/.aqbanking/ for newer versions [FIXME: Clarify version and new location].

You should encrypt this file in addition to your gnucash data file.

OS/Distribution Specific Issues

[Novell|open]SuSE

Q: Trying to open the help menu under SuSE, I get the error: "GnuCash could not find the files for the help documentation."

A: For some reason SuSE seems always to have bugs relating to the GC docs.

• You may have to use YaST to install the
  • yelp and
  • gnucash-docs packages.
• In SuSE 11.4 replacing the symlink

/usr/bin/gnome-help -> susehelp

with

/usr/bin/gnome-help -> /usr/bin/yelp

allows GC Help -> Contents to show as expected.

For older SuSE versions: gnome-help has moved from /opt/ to /usr/.

Windows

Q: I cannot get any report to display not even the sample reports. All that displays is an empty tab.

A: This is the subject of an open bug #645273. The solution, quoting from the bug report:

• Click on Start Button
• click on Control Panel
• Select Network and Internet (view by category)
• Click on Internet Options
• Select the Programs Tab
• At the bottom of the tab, select Set Progams
• Select the bottom option "set program access and computer defaults"
• You are then asked to chose a configuration:
• Extend the "Custom configuration" section and click on the radio button to use the Windows Configuration.

Note that once this configuration has been saved once, you are free to make any change you like to the "Set program access and computer defaults" section. The first change of these settings seems to cure the issue for good.

Q: When I try to open my datafile on Windows, I get "Parse error". What happened ?

A: There is a peculiarity in GnuCash on Windows when you use the Opening balance tab of the account dialog. If you enter a two-digit year in that tab, the date is not saved properly. Subsequently, when you reopen your datafile afterwards, GnuCash thinks it's invalid. If you encounter such a situation, you can attempt to fix your data file manually.

• Make a copy of your data file and uncompress it (with a tool like 7Zip).
• Open the uncompressed file with a text editor such as Wordpad or Notepad++. This is an xml file. xml looks a bit like html, but uses different tag names.
• Look for transaction sections that are missing a <trn:date-posted section>. If you find such transactions, add the <trn:date-posted> section below the <trn:currency> section, like so:

 <trn:currency>
 ...
 </trn:currency>
 <trn:date-posted>
 <ts:date>2011-07-06 00:00:00 -0400</ts:date>
 </trn:date-posted>

• Obviously, you can enter the date that suits you, but keep the format as shown.
• When all transactions have a <trn.date-posted> section, save your file.
• It should now open with GnuCash again

You could run into the same problem when you enter opening balances via the New Account Hierarchy Assistant. The solution is the same: you will have to add the missing <trn:date-posted> sections.

Note: This problem was reported in this bug and still occurs in all versions of GnuCash 2.4.x and older. It will be fixed in version 2.6.x when it is released.

Q: Windows with firewall enabled won't let me save as to a MySQL/Postgresql database on the same machine. What gives?

A: (Short version) Most likely your firewall is blocking access. Try 127.0.0.1 as hostname instead of localhost. Alternatively, you can open the appropriate ports on your firewall for MySQL access (TCP/3306) or Postgresql (TCP/5432). This alternative allows connections to your MySQL/Postgresql installation from other machines in your local network as well, which may or may not be what you want.

A: (Long version) The special hostname localhost is supposed to point back at the local machine. In most operating systems this is equivalent to the IP address 127.0.0.1. Windows is a notable exception here: it associates localhost with the IP address of your external network card. Although this address also routes to the local machine, this is theoretically the same thing. Unfortunately it is not. The Windows firewall makes a distinction between 127.0.0.1 and the network address of your network card. Since the first is truly local, it isn't filtered. The latter is connected to the outside world and as such is filtered.

So if you specify localhost as the hostname, you actually pretend to connect to MySQL on your machine from the outside and hit the Windows (or equivalent) firewall. By using 127.0.0.1 on the other hand, your connection remains truly internal and is not filtered by the firewall.

Questions about Using GnuCash

Q: Somehow I managed to close the account view tab. How can I get it back?

A: A new account view tab can be opened from the menu. This is slightly different depending on the version of GnuCash you are using:

GnuCash 2.3 and later 

View -> New Accounts Page

GnuCash 2.2.9 and before 

File -> New -> New Accounts Page

Q: Where is the Gnucash Register?

A: Go to File -> New -> New Accounts Page. You'll see a list of accounts. Click on any account and you'll bring up its register.

If you were a Quicken user, you probably don't want to see income and expense accounts in the list, at least initially, so go to View -> Filter By... and uncheck Income and Expense.

Q: How can I count the accounts or transactions in my GnuCash file?

A: If you use

• the xml backend
  • with compression enabled: zcat $DATAFILE |grep -c "act:name"
  • uncompressed: cat $DATAFILE |grep -c "act:name" on the command line
• an SQL backend: the usual SELECT COUNT(*) ...; in your DBMS

for the accounts.

Substitute 'grep -c "trn:desc"' to get the number of transactions. [2] You should also replace $DATAFILE with the right name.

Q: Is there a way to merge two accounts into one?

That is, is there a way to move all transactions from one account into another? That would save a lot of time compared to moving each transaction!

A: Kind of. If you want all the transactions in one account to move/merge into another account, you can reparent the to-be-deleted account under to to-be-moved-into account, and then delete the to-be-deleted-account. GnuCash will ask you if you want to move the transactions, and you should answer "yes".

2nd A: Probably no, you must manually change each transaction. However, there are some tricks that can make this process go a little faster. Open one of the account registers and select either View→Style→Auto-Split Ledger (or View→Style→Transaction Journal). This will automatically expand all of the splits for the selected transaction. In the simplest case, each transaction will have two splits, one of them to the current account. You want to change the split assigned to the current account to be assigned to the other account instead. Double click on the account name in the split, which should select all of the text. Now instead of using the drop-down list to select the new account, simply type the new account name, using the built-in auto-completion. For example, to move a split to Expenses:Auto:Repair, you might type ex:au:r. When you then hit <enter>, the changes will be saved, and that transaction will disappear since it is no longer tied to the currently open account.

(With the XML file backend, it is possible to merge accounts by directly editing the data file in a text editor, but this is risky and not recommended)

Q: How can I reorder accounts in the account tree?

A: Parent/Child Ordering

When editing the Child account (via "Edit Account"), you can select the parent Account. Thus, you can move Accounts up and down the tree, within the bounds of the account-type constraints. Yes, it would be nicer if one could simply drag and drop in the Account Tree.

A: Sibling Ordering

The Account Code field can contain any value you wish, which can be used in the Account Tree to sort the column and thus the rows. Unfortunately, this is a pretty heavy-handed sort that applies to the whole view, not just a sub-tree.

Q: How do I order transactions in a register so deposits are before withdrawls?

A: The "standard order" for sorting in a register is based on the entry date of the transaction, followed by the "num" field. While the granularity on the "date entered" field is down to the second internally, one can only edit the year-month-day from the register UI. As such, there are two primary ways to force the sorting of deposits before withdrawls:

1. Misuse the "num" field to control ordering.
2. Edit the datafile to adjust the hours:minutes:seconds of the <trn:date-entered> tag of the relevant <gnc:transaction> (of the deposit) to be before the withdrawl.

Q: The View menu has an option to not show voided transactions. How do I void a transaction?

A: See https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014281.html

Q: GnuCash won't let me save my customized report

I have carefully customized the options for my report and now want to save my modifications so I don't have to do all this work again the next time I need this report. But the "Save Report" button and menu item are disabled. How can I solve this ?

A: You have to change the title of your report (in the options). GnuCash will then allow you to save the report.

Q: How do I set up and track budgets?

A: There is budgeting support in GnuCash 2.0. Your testing and feedback is encouraged! See the budgets chapter in the concepts guide or Budgets elsewhere on this wiki for more info.

Q: When I print a cheque/check, the memo area remains empty... how do I fill that?

A: Fill in the Transaction Notes field, visible via View -> Double Line mode.

Q: Is there book-closing support?

A: Before answering this, it should be noted that GnuCash reports should be able to provide accurate year-end data for accounting purposes without zeroing transactions, so book-closing may not be necessary. Leaving books unclosed does mean that account balances in the Chart of Accounts will not show Year-To-Date amounts.

Many users will need to close the books however, and a number of approaches are described below.

• Using Close Book Option

Since 2.2.4, there has been a menu item for closing the books under {Tools->Close Book}. This item creates two zeroing transactions (one for expense accounts, one for income accounts). Each account in those portions of the accounts tree is reset to zero by transferring from the equity account of your choosing.

For older versions, a not-unreasonable work around is to copy your data file, and edit it to add zeroing transactions to each income/expense account.

Other methods:

• One File Per Year

1. Once your current year books are complete, create an empty copy of your Chart of Accounts by selecting File->Export->Accounts. Give the empty file the name you intend to use for the new year. This will eventually become your new set of books.
2. Next, generate a Balance Sheet report in your current year file as of your closing date and print this.
3. Save the current year books to another drive location. You may wish to copy the entire directory out, as well as burn a more permanent copy to be sent offsite for safekeeping.
4. Now, open the empty copy of your books you created. Use the Balance Sheet report you printed earlier to create opening entries for each account that needs it. You can create these as multiple transactions (one for each account), or as fewer split transactions, as you prefer.

• Yet Another Method

These are the steps:

1. record all transactions that occurred in current year
2. optional take inventory of all possessions - add the values to Fixed Assets
3. record the end value of all Asset and Liability accounts - these will be the opening balances (from Equity->Opening Balances) for the new year
4. zero out all income and expense accounts (transfer balance to Equity->Income$YEAR and Equity->Expense$YEAR accounts)
5. cancel all recurring transactions in current year file
6. export accounts (File->Export->Export Accounts) to new year file
7. Open new year file
8. Delete old or unused accounts
9. Create opening balance in new years Asset and Liability Accounts from values from current year (from step 3) from Equity->Opening Balances account
10. recreate recurring transactions
11. add StockQuote information - click on Tools->Price Editor->Get Quotes

• New Account Branch for Year-End Totals

Another method is to transfer your year-end Expense and Income totals to Equity. It is recommended to completely close out the previous year and archive a copy of your GnuCash data file before doing this.

Choose File->New Account and create an equity account for Year End transactions. For each expense and income account, create a transaction on the last day of the year to shift the balance out of the expense account into the Year End account. The account report for the Year End account makes a good summary of the information.

Some people prefer to make separate accounts for
Equity->Year End-> 2005 Expenses
Equity->Year End-> 2005 Income
so that the chart of accounts itself gives a nice summary year over year.

This method has the advantage that when entering new transactions, the auto-complete features will still work. It has the disadvantage that running reports that cross the year boundary will be skewed. Some people move any real transactions that occurred on December 31st to December 30th, so that reports can be run from January 1st through December 30th for the year.

• jGnucashEditor

The third party tool jGnucashEditor comes with a splitter-plugin that can split your gnucash-file at a given date keeping balances, accounts, invoices, customers and stock-quotes intact.

Q: How do I use variables and formula in scheduled transactions?

A: See Scheduled Transactions and the following sources:

• http://lists.gnucash.org/pipermail/gnucash-user/2005-January/012479.html
• http://lists.gnucash.org/pipermail/gnucash-user/2005-February/012964.html
• http://lists.gnucash.org/pipermail/gnucash-user/2005-May/013746.html
• http://lists.gnucash.org/pipermail/gnucash-user/2006-March/016060.html

Q: With a security that issues ReturnOfCapital in Canada, how do I include a return of capital in GnuCash?

Further information of the question: I invest in a security which issues ReturnOfCapital, which in Canada results in a decrease in the cost base of the investement for capital gains purposes.

A: Australia has similar stocks which can be handled as follows.

Remember that a debit (DR) for asset/liability accounts means an increase.

Initial purchase of security (say $1000 of Dodgy Brothers Ltd)

  Cash at bank (asset) 1000.00 CR
  Dodgy Brothers Ltd (asset) 1000.00 DR

Dodgy Brothers Ltd pays $50 dividend and $50 capital return

  Cash at bank (asset) 100.00 DR
  Dodgy Brothers Ltd (asset) 50.00 CR
  Dividends (income) 50.00 CR

This reduces the cost of Dodgy Brothers Ltd to $950.

Q: I exercised ISOs (Incentive Stock Options) for a nonpublic company, valuable only on paper. How is this represented in GnuCash?

A: Exercised ISOs (Incentive Stock Options) are stock.

1. create a "Stock" account
2. next to commodity, hit "Select..."
3. in the "Select currency/security" window, click "New"
4. Full name: (company name), Symbol: (doesn't matter), Type: (enter "Private"), click "OK"
5. once the company goes public, sell!!!

(This is not a source for tax advice, but if you do exercise private ISOs, be aware that there may be serious tax implications, even though the stock can't be sold. Be sure to talk to a tax specialist about this.)

Q: The fiscal year is July 1-June 30, how can I change that?

A: There is no way to change this in the 1.8 release. http://article.gmane.org/gmane.comp.gnome.apps.gnucash.user/12944/match=july

The adventurous might want to look at the function gnc:get-start-cur-fin-year [and it's cousins] in gnucash/src/app-util/date-utilities.scm which encode the magic value '6' [=July in a 0-based month indexing].

Q: How can I look at income/expenses/etc. on a monthly basis?

A: Run the "Income/Expense barchart" report.

Q: How do I resize my register columns? Why can I not shrink the description column?

A: To resize columns you grab the border between the column headers with the mouse, click on it, and stretch the column to the size you want. HOWEVER... The Description Column is special. It's designed to always auto-fill to fit the window size. This means that you cannot just reduce the size of the description column because as soon as you let go it will then resize itself to fill the screen. If you want to reduce the size of the description column then you should first resize the OTHER columns that you want bigger until the scrollbar appears on the bottom of the window. Then (and ONLY then) will you be able to reduce the description column back to the "full size" of the window.

This issue was reported on Bugzilla.

Note also: In version 2.4.8, problems with the Balance column were reported, with data cutoff occurring. This issue was reported on Bugzilla, along with a workaround.

Q: I corrected a mistake and now my reconciliation balance is off. How do I fix that and reconcile my account?

A: GnuCash computes the reconciliation balance on the fly from reconciled transactions. If you mistakenly (or unmistakenly!) unreconcile a transaction it will throw off the starting balance in the reconciliation process. This is completely normal and expected behavior. To correct this, just ignore the starting balance completely! All you need to do is enter in the correct ending balance and re-reconcile the transaction.

Reconciliation is purely about the ENDING balance at a point in time. When you reconcile you're saying that at some Date (the reconciliation date) the account has some ending balance X, and you're marking all the transactions that get you to that ending balance from the beginning of time. The starting balance is there to guide you, but has no relevant meaning in the reconciliation process. Actually, thats not 100% true -- the starting balance gives you the total of the already-reconciled transactions from the beginning of time that are already included in the computation. But that's okay, you can still generally ignore it. If you unreconcile a $1 transaction then your starting balance will be off by $1, however all you need to do is re-reconcile that $1 transaction the next time to bring it back into balance.

No, this doesn't work Somehow, GnuCash got into it's head that I had a starting balance of -2465. When it happened to me, this was the opening month of my acount. It has marked everything in the account which needed to be reconciled, however I was still short somewhere on the range of $4000.00. As such, the finish button was greyed out, and I can't continue. This is NOT an ignorable issue.

However, there is a way to fix. Here is the crux of the issue. If you delete a reconciled statement, GnuCash doesn't do anything. So, go ahead and enter reconciliation with the correct ending balance. Add a transaction which deposits money (given the starting balance GnuCash has is lower) or withdraws money (if gnucash has a higher balance) from the account in question. For mine, I added a deposit of 2465. as I needed a starting balance of 0. Reconcile as normal (it should now come to zero, or else you have a different problem), and click finish. After you are done, click on the transaction that you added to cause things to work out, and delete it. Your books will be correct, and now you can continue reconciling as normal.....

This is a problem, and should be fixed with a dynamic and/or editable starting balance...

Just enter a correcting transaction to get the starting balance you want. The account to transfer funds to/from would probably be Equity:Opening Balances. For example,

I hope that helps.

Jonnybal 07:13, 10 March 2010 (UTC)

Q: I would like to add transactions from the command line with "gnucash --evaluate something". How do I do this?

A: This is not possible. You would need to convert the external transactions into a shared format such as QIF or OFX and import them using the existing application functionality.

Importing/Exporting Data

Q: How can I export data?

A: There's an XSLT at http://xslfactory.free.fr/ which can transform a gnucash XML file to a big Gnumeric spreadsheet. The Workbook will contain several sheets; One with all the accounts, a diary with all the transactions, and on sheet by account with all the transactions. Prior to running the transform, you'll need to edit the gnucash XML file (preferably a copy of it) to include xmlns data. (Note however that as at 24th Apr '04 it doesn't include support for business objects, eg: invoices.)

The xlsfactory version of the xslt spreadsheet is version 0.6. There is also a 0.7 version at http://sites.google.com/site/gnucashexport/.

There is also http://gnucashtoqif.sourceforge.net/ which is a Java program that can transform a gnucash XML file to a QIF file.

One way to easily export GnuCash data to Excel or LibreOffice Calc is to find a report (such as the General Ledger) that you can adjust to a satisfactory output, and export the report to an HTML file. Then open the HTML file from Microsoft Excel. (Using File>Open from within Excel, selecting "html" as the file type.) The Excel program will load the report into a spreadsheet, allowing filtering and other spreadsheet functions.

As of the 2.0 release series, the GnuCash data file may be compressed. Just gunzip the data file to see the raw XML. Alternatively you can change the saving state of the GnuCash data file by going to the General tabbed page in GnuCash Preferences dialog box (Edit->Preferences->General) and toggle the compression feature.

Some scripts have been created to move gnucash data into a mysql database.

There is an OpenOffice.org macro (Download here; download link on the other site is broken) which reads GnuCash data and imports them into OpenOffice.org's embedded database so that they can then be analyzed e.g. in OpenOffice.org Calc. Business accounts and multiple currencies are not supported.

Ledger-CLI shows export to Ledger, which uses a CSV like file format.

Q: Can I import historical prices or quotes?

A: If your GnuCash version is built with Python Bindings, you can use the scripts shown on these pages:

• Stocks/get prices and
• Importing fund or stock prices from an OFX file.

Q: My bank doesn't offer OFX or QIF but only CSV or similar. How can I import my statement data?

A: QIF is a flat text file of a specific format, only a few steps removed from CSV (comma separated values). There are scripts that can do the transfer. Take a look at how another GnuCash user has solved your problem: http://baruch.ev-en.org/proj/gnucash.html "I very quickly found that I'm way too lazy to hand enter the bank statements into GnuCash" From the same site:

It is possible to have a Perl script that was written to download the data from the Bank internet site, modified to adapt it for my needs, which is simply to export the data in CSV format. I then wrote a Python script to convert the CSV data to QIF format. The QIF files are easily imported into GnuCash with relatively very few keystrokes."

GGInternational.net provides a Free Online Converter which runs on any Internet Browser in any platform, such as Windows/Mac/Linux.

You have the ability to save your mappings to re-use it when importing from the same bank.

You can use the Splitter type to save multiple QIFs from a single CSV with multiple accounts.

Sleek layout and great user interface allowing you to go through the CSV contents before you map it.

Please visit this link to starting importing few clicks away: [CSV to QIf Converter http://csvtoqif.gginternational.net/]

Q: How do I convert from CSV, TSV, XLS (Excel), or SXC (OpenOffice.org Calc) to a QIF?

A: If the CSV file has values for the date, description, amount and account of a transaction, then it's possible a simple `awk` script might work to convert the CSV file into QIF. Let's say the CSV file "statement.csv" has the columns ( date,description,amount), as in:

   2006-09-27,ONLINE BILL PAYMENT: Bank of Example 123938568,250.00

As such, the following shell script using awk will emit a suitable QIF:

   $ ( echo '!Type:Bank'; cat statement.csv | awk -F, '{ print "D" $1; print "P" $2; print "T" $3; print "^"; }' ) > statement.qif

See The Wikipedia article on the QIF format for more details about the QIF format.

Another way is to use the macros that exist for Excel and OpenOffice.org. These macros will convert a spreadsheet file into a QIF file. XL2QIF is a script to convert an Excel spreadsheet to a QIF file. CALC2QIF is a script to convert an !OpenOffice.org spreadsheet to a QIF file. These macros may be obtained at http://xl2qif.chez-alice.fr/calc2qif_en.php.

Jeroen van der Vegt has changed the csv2qif by Baruch Even for the (Dutch) Rabobank asc files. The python script is available at http://www.gertvanbraak.com/rabobank.py The original file by Baruch can still be downloaded from http://baruch.ev-en.org/proj/csv2qif (Python)

--Zachary 21:12, 22 November 2006 (EST) I've written some C++ code to convert TD Ameritrade csv files to qif. That in turn is based on earlier work from John McKown.

Tomas Edwardsson has created a few scripts for converting data from Icelandic banks into QIF. They can be downloaded from http://tommi.org/gnucash/ (Perl)

Dave sent the following links on the mailinglist:

1. *csv2ofx* http://github.com/mulicheng/csv2ofx/tree/master
2. http://www.mt2ofx.tk/
3. http://xl2qif.chez-alice.fr/calc2qif_en.php

I played around with the German Raiffeisenbank CSV exports. Since it has German-style number and data formatting and other intricacies, even GnuCash 2.3.2 cannot import it. I used the existing Mastercard csv import as a base and modified it to read these files correctly. Note that right now, "EUR" is fixed as currency. Happy to share the file but don't have access to it right now; please email me at post-at-christophd.de and I'll send it.

--Christophd 07:54, 15 July 2009 (UTC)

GGInternational.net provides a Free Online Converter which runs on any Internet Browser in any platform, such as Windows/Mac/Linux.

You have the ability to save your mappings to re-use it when importing from the same bank.

You can use the Splitter type to save multiple QIFs from a single CSV with multiple accounts.

Sleek layout and great user interface allowing you to go through the CSV contents before you map it.

Please visit this link to starting importing few clicks away: [CSV to QIf Converter http://csvtoqif.gginternational.net/]

Converting Postbanken's CSVs to QIF (might also work with other norwegian banks, like DnB NOR):

Download this awk file: http://dl.dropbox.com/u/8186126/postbanken.awk

Usage: awk -f postbanken.awk kontoutskrift.csv > import.qif

Q: Can I import my (USA) Discover credit-card info?

A: See Setting up OFXDirectConnect in GnuCash 2. From OFX Direct Connect Bank Settings, the settings you want to use are https://ofx.discovercard.com/ for the Server URL and 7101 for the FID.

Q: My bank offers OFX Direct Connect. How do I use that?

A: GnuCash uses libofx/aqbanking for OFX/QFX support, so you should look there for Direct Connect support: http://aquamaniac.de/aqbanking/ . Also, there is a python script available that can do this for you at [ http://www.jongsma.org/gc/ ].

A: Information on setting up AqBanking for OFX Direct Connect in Gnucash 2 is now available at Setting up OFXDirectConnect in GnuCash 2. --Dbreiser 00:45, 22 September 2006 (EDT)

Q: Can I connect GnuCash to stock or mutual fund accounts using OFX Direct Connect?

A: Aqbanking doesn't know about stock/mutual fund purchases/sales. Instead, download your OFX/QFX data file from your broker's website and use libofx to import it into gnucash. Libofx is used by the File>Import>Import OFX/QFX... menu choice.

Q: Which is the best way to import data from Quicken(TM)?

A: Start by making an account tree in Gnucash. There is a druid to help you, but keep at this stage to very similar names as you have used for categories and accounts in Quicken. Next export your Quicken data to a QIF format. Save this file. From the Gnucash menu select File > Import > Import QIF. Open your QIF file and follow the prompts. Match each category very carefully to your Account tree. Clicking on a highlighted line will allow you to choose from your new account tree. Match as much as you can. Then complete the import process. Look at the results and be prepared to alter the account structure and start again if you have too many "Unspecified" entries.

An alternative approach to creating the account tree in Gnucash first is to include your categories and accounts in Quicken's QIF export. This option is available in many versions of Quicken. If you have this data in the QIF file, Gnucash will create your accounts automatically. After the import is completed, you can edit individual Gnucash accounts and reassign them as needed.

Note that you cannot import a QDF file into GnuCash, and there are no plans to add "QDF" support anytime soon.

Q: How do I import my data from Quickbooks(TM)?

A: At this time there is no way to import from Quickbooks, and there are no plans to add that functionality. The Quickbooks QBW data format is a proprietary, non-documented file format. So until someone documents the file format or donates a QBW file parser your best bet for importing your QB data into GnuCash would be to output your data in a CSV format and either import the CSV data directly or convert the CSV to QIF and use the QIF importer.

Q: How do I import my data from Microsoft Money?

A: To transfer data use the Export Function of Mirosoft Money. Use the Loose QIF (longer names) format if available. GnuCash will create your accounts automatically from the information in the QIF files. When exporting Microsoft Money records each transation twice, once in each account's QIF. Thus for the conversion to be successful all accounts must be loaded and the Account names must match to enable GnuCash to remove the duplicates. It may be more convenient to enter Stock Codes in the Securities editor prior to importing.

Adjustments for Accounts

Investment accounts do not record the account names in the QIF files so if an error is made in entering the account name the transaction will be duplicated. The account names can be included in the file by placing the following text at the beginning of each file:

!Account
NName of Account Here
TInvst
^

Asset accounts should start with a zero balance to import successfully otherwise the asset has no balancing transaction (it has to come from somewhere!).

Adjustments for Transactions

Check for any transactions with one side in the unspecified account. These are transactions with no category specified. You should enter a category in Microsoft Money for these and transfer the data again.

A transaction with two splits one of which is a transfer adding to zero in a single account may not transfer properly. Replace the two splits with a single transaction to the target of the transfer.

Final Checks

After conversion examine the account balances and compare with the final account balance reports from Microsoft Money. Any liabilty accounts will probably have the wrong type and a negative balance in GnuCash. Edit the Account and correct the type.

Also check the category spending over all time from Microsoft Money with the Accounts in GnuCash.

Once the accounts are consistent with Microsoft Money you can edit individual Gnucash accounts and reassign them as needed.

Stock Prices, Budgets and Scheduled Bills and Deposits will need to be copied manually.

Q: While attempting to import a QIF file created by Microsoft Money, I got the message, "A bug was detected while reading the QIF file", even though I had entered a preference for vebose error messages. Why do I not get something more informative such as a statement of the specific deviation from the QIF specification and the line number where it occured?

A: Did you read Something bad happened; how can I help debug? and around?

Console output, log file, ...

Using Business Features

Basics

Q: Can you give me a high level overview for business users?

A: Here is the GnuCash Quick Start Guide For Business Users. A short visualisation can be seen in gnucash per fatturare in ca 2 minuti.

Q: What are the usual Billing Terms?

A: see Invoicing and payment terms.

Set Up, Opening

Q: Is there a wizard or a description to setup basic business accounts?

A: No. There are some basic business template accounts (e.g. for DE, US) in the "New file" druid/wizard. But there are no wizards/druids for setting up a business, i.e., setting up tax tables, terms, customers, and vendors. You can do all that under the Business menu.

If Gnucash is lacking business template accounts your region and you are volunteering to share your newly created account charts, please follow the instructions at Translation#How to translate the files containing the new account hierarchies.

Q: How do I set up the individual customers and vendors, with their respective balances?

A: There are no "opening balances" for the business features. The only way

to setup an "opening balance" for a Customer (or vendor) is to create a throwaway Invoice (or Bill) for that opening balance.

Q: How do you make the organization name appear on my Invoices?

A: You can go to File -> Properties and set your business' name and address on the Business page. The Invoice printer uses the data from this entry to fill in your business information. See also #Q: How do you make the organization name and information appear at the top of reports? on screen, and when you print?

General Handling

Q: How can I delete an Invoice, Customer, Vendor, or Employee?

A: Quick answer: you can't. Longer answer: you can mark the item as "inactive" (just uncheck the "active" button) and it will no longer show up in standard searches. There are no plans to ever allow you to delete these objects. If you really care you can just re-use them later.

A: Quick answer: you can. Longer answer: 1 - delete Invoice entries (GncEntry clause), 2 - delete Invoice of these deleted entries (GncInvoice clause), 3 - Customer of these deleted Invoices (gncCustomer), 4 - correct counters (count-data) for those deleted positions. Try to learn database file structure. It takes one hour for me.

A: Longer Answer. You can delete them, but it is going to involve editing the XML file yourself. Take a deep breath, it's going to be okay. I'd also just like to note that while this seemed to work fine on my machine, I can't promise you 100% that this will work. Please, please, please backup before you do this. Alright, now that all that is out of the way, lets do it.

• I am going to suggest that you clean out all the Invoices you want to delete before you do this. So go into the invoice and delete all the entries that exist in it. That will make removing data much easier.
• First we're going to need to ungzip your gnucash file (make sure you're working in a separate directory from the directry that you ususally save your data file and that you've copied the latest version of the data file to this directory). Rename the data file to something that ends in '.gz'. So if your data file is named accounts rename it to accounts.gz.
• Then run gzip -d accounts.gz. This will create an unzipped file with the name of accounts
• Open up accounts in your favorite text editor.
• The GnuCash xml format is pretty simple, but there is probably going to be a lot of data to wade through. You're going to have to start at the top of what you want to delete and work your way down.
  • If you're deleting a Customer, then you start there, then move down to all its jobs and then down to all the invoices and finally to the entries (but you shouldn't have to do this if you cleared out the invoices first.
  • If you're deleting a Job, you start with the Job, then work down to all the Invoices.
  • If you're deleting an Employee, start with the Employee and then delete all the invoices.
  • If you're deleting an Invoice, just delete the Invoice.
• I'm going to take the case of deleting an Employee for the example. The first thing to do is to find the GncEmployee line that corresponds to the employee you want to delete. Go ahead and search the document for the string GncEmployee. This should take you right to the first employee in the file. Scroll down until you find the user you want to delete. Don't just delete the user. Select all the text that represents that user, from the <gnc:GncEmployee version = "2.0.0"> to the final closing </gnc:GncEmployee> tag. Cut it and paste it into a temp file. Make sure you remove any extra line breaks (there shouldn't be any blank lines left). So you've just gotten rid of the employee.
• Now you need to go find all the invoices associated with that Employee. In the temp file, find the line that starts with <employee:guid type="guid". That value if the unique ID number that gnucash uses to identify that employee in the xml file. So now copy that value, return to the data file and do a search for that guid.
• Each time you seach, you should land inside a GnvInvoice block. Delete the entire block, again making sure that you aren't leaving any spaces.
• The last thing you need to do is clean up the counters in two places. You only can do this if you're deleting the LAST thing that you added. So if you have an employee and it is the last employee you added, you can fix the employee counter. If it is an Invoice and it is the last invoice you added, you can fix the invoice counter. DO NOT CHANGE THE COUNTERS IF WHAT YOU'RE DELETING ISN'T THE LAST THING ADDED.
  • Go back to the top of document. Find the block that starts with <book:slots> Inside that there should be a section labeled <slot:key>counters</slot:key>. Under that you'll find a slot:key line for each type, for example GncEmployee. Underneath that is a slot:value. Decrease the value by one.
    • In SQL:

SELECT * FROM slots WHERE name="counters/gncInvoice"; ...

• Then scroll down a little farther and find the <gnc:count-data> fields. Find the one that corresponds to the counter you're decreasing and lower it by one as well.
• Save your changes.
• Run gzip to compress the file. run gzip -9 accounts. Then rename the accounts.gz to accounts
• Open the file with gnucash. Verify everything works right. You probably want to check account balances against what they used to be to ensure that they're right, etc. If it doesn't match, you messed up somewhere and you're going to have to go back and do the whole thing over again. Otherwise, you're good to go.

Q: Will I be able to delete an Invoice, Customer, Vendor, or Employee in the future?

A: That's not implemented because the logic to determine that it's safe to do is... hard. There are so many interconnections between Invoices, Bills, line-items, Tax Tables, etc that making sure it's safe to delete an invoice without leaving dangling references was just ... a lot of work. Work that I personally didn't want to do, and nobody else has come along with a way to do it securely.

Patches are, of course, always welcome. But be warned, it's not a simple task. Which is why it was never implemented, and why we have the "active" flag as a way to remove items from searches.

I'm sorry you don't like it. You're welcome to help fix it.

[from the mailing list [3]]

Q: Can I pay multiple bills/invoices/vouchers with a single payment?

A: Yes. When you make a payment in GnuCash you are making it against an account, not against a specific bill (or invoice, or voucher). Naturally you can only pay multiple bills from a single account in this way. Any payment you make to the account will be matched against the outstanding bills in the account in date order, earliest first (FIFO order). GnuCash will also split the payment transaction to match the individual bills. Processing payments in this way can be done from any process payment option simply by changing the payment value.

Tax Handling: Goods and Service Tax (GST) or Value Added Tax (VAT)

Q: How do I handle VAT/GST on invoices, and claim VAT/GST rebates on purchases?

Appearance and printing of Invoices etc.

Q: How do you make the organization name and information appear at the top of reports? on screen, and when you print?

A: You can edit the Style Sheet (Edit -> Style Sheets) and set your company information there. That's probably the best way of doing it. You may want to create a new Style Sheet if you don't like the existing ones. The template stylesheet (stylesheet-fancy.scm) can be found in your_gnucash_directory/share/gnucash/guile-modules/gnucash/report/ . To meet Australian requirements, include your ABN as a separate line in the business address.

The template stylesheet (stylesheet-fancy.scm) also allows you to set how large your company logo appears at the top of reports. To set this search in the style sheet for the line ' "<img src=\"" headpixmap "\">" '. Change this to ' "<img src=\"" headpixmap "\" width=\" 300\">" ' - with 300 being the width of the logo - change this figure of 300 until the logo looks good when printed. Setting the logo size here allows you to avoid the print quality problems that will come with reducing the logo size by changing your logo dimensions in pixels i.e. resizing the image in an editing program. 300 pixels per inch is the guide for a good quality print - so a 300 by 300 pixel logo image should be printed at about 1 inch square - if your logo looks pixelated when printed see if using a version with more pixels works better.

Q: How do I customise the default invoice report options so my printable invoices always load with the options I want?

A: The easy workaround is to change the options as you like and then leave the report open in a tab, simply changing the invoice number as necessary.

Alternatively, you can preset the default options by editing invoice.scm (found at /usr/share/gnucash/guile-modules/gnucash/report/invoice.scm - at least that's where it is on Ubuntu 8.04) as follows.

Please note this file controls the Printable Invoice; if you want to customise the Fancy Invoice, you need to edit fancy-invoice.scm.

The default options are found starting at about line 241, which looks like this

 (gnc:register-inv-option
  (gnc:make-simple-boolean-option
   (N_ "Display Columns") (N_ "Date")
   "b" (N_ "Display the date?") #t))

and finishing at about line 325 which looks like this

 (gnc:register-inv-option
  (gnc:make-text-option
   (N_ "Display") (N_ "Extra Notes")
    "u" (N_ "Extra notes to put on the invoice")
    (_ "Thank you for your patronage")))

VERY IMPORTANT. Before you change anything, please copy the original file to a new name: If you do make a mistake you may find that Gnucash won't start any more. You may also want to keep a copy of your edited file somewhere safe as when Gnucash is upgraded the file may be over-written and you would lose your changes.

For the boolean options from line 241 to line 319 you can choose between #t for TRUE and #f for FALSE.

You can change the text at the bottom of the invoice from "Thank you for your patronage" to anything you like but "Pay up ****head!" is unlikely to gain cooperation from your customers.

Jonnybal 07:57, 10 March 2010 (UTC)

Q: How do I remove the Tax column?

A: In the report options, deselect the "Tax Amount" column in the "Display Columns" tab. To make this change permanent next time you start Gnucash you will need to edit invoice.scm or fancy-invoice.scm as follows.

Set the following section in lines 276 to 279 to FALSE (that is #f instead of #t). This means your invoices won't display a tax column for all the line items.

 (gnc:register-inv-option
  (gnc:make-simple-boolean-option
   (N_ "Display Columns") (N_ "Tax Amount")
   "m" (N_ "Display each entry's total total tax") #f))

Jonnybal 07:57, 10 March 2010 (UTC)

Q: My business does not charge tax. How do I remove the Tax total line?

A: It's probably better to leave the "Tax Total" line in even though it shows zero tax. Your customers need to know if your invoice includes tax as they might claim the tax back. They will look for the Tax line and if it shows zero they will know there is no tax to claim. If the tax line is missing then they have to guess whether the Amount Due includes tax or not and most likely they will phone you to ask.

If despite this, you really want to remove the "Tax Total" line, you can do this by selecting the "Individual Taxes" checkbox in the "Display" tab of the report options. At first sight this seems odd, but it works because instead of displaying a tax total, the tax is showed as a column on each line item. If you also turn off the Tax Column as above then no taxes are shown at all.

To make this change permanent edit invoice.scm or fancy-invoice.scm as follows. In my invoice.scm its the section beginning at line 286.

 (gnc:register-inv-option
  (gnc:make-simple-boolean-option
   (N_ "Display") (N_ "Individual Taxes")
   "o" (N_ "Display all the individual taxes?") #t))

Q: I have turned off the Tax Total line. How do I remove the Sub Total line?

A: In my invoice.scm, its the section beginning at line 419. You will see I have commented out some lines to remove the subtotal line.

      (if (null? entries)
	  (begin
; I have commented out the next two lines to remove the Subtotal
;	    (add-subtotal-row table used-columns value-collector
;			      "grand-total" (_ "Subtotal"))

Q: Can I print Invoices through LaTeX from GnuCash?

A: No, not directly. However, other users have created separate tools that can do this for you: http://stefans.datenbruch.de/gnucash/gc2latex.shtml and http://www.smoerz.org/gcinvoice. The latter can create invoices from arbitrary user provided templates.

Using Multiple Currencies

Q: Posting invoice or bill results in zero value transaction in Accounts Payable or Accounts Receivable - why and how to fix this?

A: This probably happens because you have a currency conflict within your invoice or bill.

Each invoice or bill may only use one currency. When you create an invoice for a given Customer, GnuCash takes the currency setting for that Customer and uses it for the invoice. If any of the accounts you refer to from the invoice — the Accounts Payable account, the Income:Sales account, etc. — use a different currency, then when you post the invoice, GnuCash will post a value of 0 instead of the amount from the invoice. GnuCash (as of 2.2.8) also fails to give an error message about the conflict. Similar limitations apply with Vendors and Bills.

To prevent the problem, follow the instructions in the next answers:

Q: How can I set up a customer or supplier in a foreign currency?

A: To set up customers and vendors in foreign currencies do the following:

• Define the currency for the Customer. Select the Customer and click on Edit Customer, then click on Billing Information - that will show you the customer currency. Change it to whatever Currency you will use with that currency.
• If you use multiple currencies with a single Customer, you have two choices:
  • You can make multiple Customer entries for that customer, each one with a different currency. Put something in the Customer ID or Customer Name to make it easy to tell them apart. Always select the Customer entry appropriate for the invoice you are entering. Or
  • you can convert any amounts in a different currency to their equivalent in the Customer entry's Currency before entering the amounts in the invoice.
• Confirm the currency defined for each Account. Select the account in the Chart and then click on Edit Account - that will show you the account currency. Change it as needed.
• If you create invoices in multiple currencies, you will probably be best served by making multiple Accounts Receivable and Accounts Payable accounts, one for each currency you work in. Similarly, you will probably want to create multiple Income:Sales and Expense:Reimbursable Expense accounts, one for each currency. Consider using a suffix after the account name to make it clear which currency that account uses: for instance, "Accounts Receivable (CAD)", "Accounts Receivable (JPY)", etc.

Q: How can I fix already in a wrong currency posted invoices or bills?

A: To correct this problem with already-posted invoices, do the following:

• Find the invoice. Edit it.
• Unpost the invoice. Click OK at the confirmation dialog
• Check the Customer's Currency value by clicking on the Billing Information... Customer... Edit... button. The Edit Customer dialog appears.
• Click on the Billing Information tab. Look at the value for Currency there.
• If this currency value is incorrect in general, i.e. you selected the correct Customer entry, but for this Customer you always use a different currency, then select a new currency value from the popup menu and click OK. Your invoice currency may now be corrected. (If this isn't sufficient, follow the steps below to select a different Customer entry, close the invoice, and then re-edit the invoice to select the original Customer entry. This will most likely reset the Invoice's Currency setting.)
• If this currency value reveals that you selected the wrong Customer entry, then don't make a change here. (This may occur if you have multiple Customer entries for one multi-currency customer, each with a different currency setting.) Instead:
  • Click Cancel to dismiss the Edit Customer dialog.
  • Click the "Edit Invoice" button in the toolbar. The Edit Invoice dialog appears.
  • Under Billing Information... Customer... click the Select... button. The Find Customer dialog appears.
  • Enter search terms, and click the Find button. A list of customers appears. Select the Customer with the correct currency setting. Click the "Select" button. The Find Customer dialog disappears.
  • Click the "OK" button. The Edit Invoice dialog disappears. Your invoice currency is now corrected.
• Check the Accounts listed in the Income Account column. Verify that each one is in the correct currency for the invoice. Make this check as follows:
  • Look at the name of the account.
  • Then click on the Accounts tab just below the toolbar. The Accounts list appears.
  • Find the account in the list. Select it.
  • Click the "Edit" button in the toolbar. The Edit Account dialog appears.
  • Under Identification... Security/Currency, check that the currency setting is correct.
  • To change the currency value, click the "Select..." button. A Select Currency dialog appears. Click the triangle button to the right of "Currency:". A popup menu of currencies appears. Select the correct currency. The popup menu disappears, and the new currency value appears in the dialog. Then click OK. The Select Currency dialog disappears.
  • In the Edit Account dialog, verify that the correct currency name appears in the Security/currency field.
  • Click the OK button. The Edit Account dialog disappears.
  • Click on the "View Invoice – ..." tab. The Invoice line items reappear. The currency for that account is now correct.
• The currency conflict should now be resolved. The Customer and each of the Invoice Entries should now use the same currency.
• Click the "Post" button on the toolbar to redo the Post operation. The "Question" dialog appears, asking, "Do you really want to post the invoice?"
• In the "Post to Account" field, confirm that the Accounts Receivable account selected has the correct currency. If it does not, correct it as follows:
  • Click the down-arrow to the right of the Post to Account. A menu of Accounts Receivable accounts appears. If one has the correct currency, select it.
  • If you don't have an Accounts Receivable account, click the "New..." button. A New Account dialog appears.
  • Under Identification... Security/Currency, check that the currency setting is correct.
  • To change the currency value, click the "Select..." button. A Select Currency dialog appears. Click the triangle button to the right of "Currency:". A popup menu of currencies appears. Select the correct currency. The popup menu disappears, and the new currency value appears in the dialog. Then click OK. The Select Currency dialog disappears.
  • Back in the New Account dialog, verify that the correct currency name appears in the Security/currency field.
  • Fill out the other fields (Account name, account code, etc) for the account.
  • Click the "OK" button. The New Account dialog disappears.
  • Back in the "Question" dialog, confirm that this account is now listed in the "Post to account" field.
• Also Confirm that the Post Date, Due Date, Description, and "Accumulate Splits?" settings are correct.
• Click the OK button. GnuCash posts the invoice.
• In the toolbar, click "Close" to close the invoice.
• Check the transactions under the various accounts to be sure that the amounts for this invoice are no longer zero, but instead have the correct values.

GnuCash Bugzilla entries relating to this FAQ:

• Bug 583155 – Invoice creation and posting silently inserts zero amounts when currencies conflict, no error message
• Bug 430187 – Posting an invoice returns Zero values to the ledgers with NZD currency

Country/Region specific

Q: I have a small business in Norway. How do I use GnuCash to meet Norwegian standards?

A: There is a special page on Accounting your Business in Norway.

Q: Is GnuCash compliant with standards of UK Authorities?

A: There is a special page on Pas 76

Q: How do I change "Invoice" to "Tax Invoice" as required in Australia?

A: Edit invoice.scm and change (define invoice-name (N_ "Invoice Number" )) to (define invoice-name (N_ "Tax Invoice Number" )). If you are using tax tables to calculate GST and add it as an automatic subtotal, then you should also change the line "grand-total" (_ "Tax"))) to "grand-total" (_ "GST"))). There's another section around line 630 which says (title (_ "Invoice")) which should be edited similarly. If you use fancy invoice, look around line 705 for this: (gnc:html-table-cell-append-objects! invoice-cell (_"INVOICE")) Also in Easy Invoice From ->(add-html! document (sprintf #f (_ "Invoice #%d") To -> (add-html! document (sprintf #f (_ "Tax Invoice #%d")

A better way would be to substitute invoice.scm and the other similar files, fancy-invoice.scm and easy-invoice.scm, with files allowing editing of tax names and titles such as the ones in this gnucash devel list thread entitled World friendlier printable invoices. Make sure to close all reports before updating the files.

Accounting Questions

Q: Can you recommend a book on Accounting?

A:

On-line:

• http://www.dwmbeancounter.com/tutorial/lesson01.html
• http://www.middlecity.com/
• Accounting & Bookkeeping Tips
• http://www.principlesofaccounting.com/

Dead-tree:

• Schaum's Outline of Bookkeeping and Accounting
• Schaum's Outline of Principles of Accounting I
• The Complete Idiot's Guide to Finance and Accounting by Michael Muckian.
• Keeping The Books by Linda Pinson

Q: What are debits and credits?

A: Debits and credits are the terms used to identify either an increase or decrease in an account. It depends on the type of account that you are talking about as to whether the increase or decrease is a Debit or a Credit. The first step in understanding debits and credits is to forget what your bank tells you. As they are looking at it from their point of view, when they tell you that they will "credit" your bank account (in other words, put money in your account) they are correct. However, to you it is a Debit. Here's why.

Let's start with the accounting equation: Assets = Liabilities + Equity, where Equity = Revenue - Expenses (actually equity is more than just that, but for the purpose of this explanation it will do).

Now think of each of these catagories (Assets, Liabilities, etc) in terms of a T, with the name of the catagory above the top of the T and the transactions being recorded on either side of the vertical part of the T. Debits are recorded on the left side of the T, Credits are recorded on the right side of the T. Lets look now at the Asset accounts. Since the Assets are on the left side of our equation, any increase in assets must be recorded on the left side of our T, this means that an increase in assets is a Debit. Conversely, a decrease in an asset account must be recorded on the right side of the T, meaning that it is a Credit. Looking next at Liabilities and Equity, it is treated exactly opposite to Assets (otherwise the equation wouldn't work). Because Liabilities and Equity are on the right side of the equation, any increase in Liabilities or Equity are recorded on the right side of the T. This means that it is a Credit. A decrease in Liabilites or Equity would then be recorded on the left side of the T, or a Debit.

Now for Revenue and Expenses. Since both of these are a component of Equity, whether they are a Debit or Credit is tied into how Equity fits into the accounting equation. Think of it this way, if you made money during the year, the net effect on your Assets would be an increase, or greater Debit balance. In order for the equation to work, this would mean that Equity would also have increased, or a greater Credit balance. In order for this to happen, Revenue would have to be a Credit, while Expenses would have to be a Debit. The resulting Revenue minus Expense would give you a Credit balance, or an increase in Equity. So Revenue is always a Credit, while Expenses are always Debits.

To go back to the what the bank is telling you, here is why they are right from their point of view. They owe you money (your bank account balance). This, to them, is a Liability. Therefore, any increase in the amount they owe you would be a Credit on their books. However, to you, your bank account is an Asset. Therefore, any increase in your bank account would be a Debit on your books.

Q: How do I record my income tax installments and year-end payment/refund?

A: The difficulty in recording your income tax expense is that you don't know until the year is over what your true expense for the year will be. Because of this, there is no way to accurately record the income tax expense on a monthly basis. My recommendation is to record the monthly installments to a balance sheet account, then, when you complete your tax return for the year and know the expense, record the expense to the income statement account.

Let me illustrate by the way of example. First, I'll make some assumptions:

• Year end is December 31, 2004
• Monthly installments of $100.00 are required to be paid
• The tax return is completed and filed on March 31, 2005 along with a cheque for the balance payable
• Total taxes payable for the year are $1,300.00. This means that after the installments of $100.00 per month, $100.00 is still owing.

You will need to add the following three accounts, if you don't already have them.

• Income taxes payable (Liability account)
• Income taxes receivable (Asset account)
• Income tax expense (Expense account)

The first entry will be to record the first installment. Post this as a credit to your bank account and a debit to the income tax payable account. Repeat this same transaction every month. In fact, you could set it up as a scheduled transaction. At the end of the year, you will have accumulated $1,200.00 in the income tax payable account.

On March 31, 2005, make an entry dated for December 31, 2004 to record the expense for the year. This would be a debit to the income tax expense account for $1,300.00 and a credit to the income tax payable account. As a result of this entry, the balance in the income tax payable account is a credit balance of $100.00, and the balance in the income tax expense account is a debit balance of $1,300.00.

The final entry would be to record the cheque on March 31, 2005 to pay the balance. This would be a credit to the bank account for $100.00, and a debit to the income tax payable account for $100.00.

The next question is what happens if I have a refund. Let's assume that you only owed $1,100.00. This time, when you record the expense (dated December 31, 2004), you would debit the income tax expense account for $1,100.00 and credit the income tax payable account. This results in a debit balance in the income tax payable account of $100.00. Since this is really a receivable, it needs to be moved to the income tax receivable account. Do this by debiting the income tax receivable account for $100.00 and crediting the income tax payable account. When the refund is received from the government, record it as a debit to the bank account for $100.00 and a credit to the income tax receivable account.

Q: How do I use GnuCash to calculate VAT?

A: Frequently discussed on the mailing list, someone please copy answer here...

• "UK company VAT account structure, updated"
  • https://lists.gnucash.org/pipermail/gnucash-user/2003-July/007526.html
• "Handling GST and PST from Credit Card transactions"
  • http://lists.gnucash.org/pipermail/gnucash-user/2005-January/012791.html
  • http://lists.gnucash.org/pipermail/gnucash-user/2005-January/012807.html

Q: How do I use GnuCash to do depreciation?

A: Please check the chapter about depreciation in the Concept Guide

Q: Is there a CPA (Certified Public Accountant) who uses GnuCash in my area?

A: If you are an accountant or bookkeeper, add your name and contact info here.

Raleigh, North Carolina	Kenneth M. McNees, CPA, CISSP, CISA, CAP, CISM.		kennymcnees@gmail.com	added: December, 2007
Egg Harbor Township, NJ	Jeff Vandrew Jr, CPA		jeffvandrewjr@vandrew.com	added: May, 2010	http://www.vandrew.com

Q: What's a T-account? What's double-entry?

A: This is discussed at length in the GnuCash documentation. Also, Wikipedia's entry for Double-entry bookkeeping is good.

Q: Is there a way to schedule billing the same way we schedule transactions?

A: No, unfortunately, the business features don't tie into the SX engine.

Q: How do I account for loaning/borrowing money to/from a friend?

A: Money that you loan to someone represents an Asset to you. Money you've borrowed from someone else is a Liability. The general recommendation for account names is:

• Assets:Money Owed To Me:[Person]
• Liabilities:Money I Owe To:[Person]

Q: How do I keep track of capital gains with stocks?

A: The 1.8 series of Gnucash doesn't handle capital gains in an automated fashion, so it's pretty easy to get an incorrect balance sheet after the sale of stock or some currency conversions. Recall that in the double-entry accounting that Gnucash uses, money is never created or destroyed, it only moves from one account to another...at least, in theory. The introduction of stock transactions (or really anything that involves an exchange rate) creates a situation where money can be created.

For example, let's say we have the following accounts:

Assets
  Broker
    Cash
    XYZ Inc
Expenses
  Broker Fees
Income
  Capital Gains

When we purchase stock in company XYZ, the transaction splits might look like this:

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      5        $10.00  $50.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                                    $57.00

This is pretty straightforward. We bought five shares at $10 each, and paid a $7 commission. But you have probably already gotten this far and now you're ready to sell. If you entered the intuitive splits, money would be created and everything would get thrown out of balance:

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      -5       $17.00            $85.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                           $78.00

$35 has come from nowhere! It's actually capital gains, but we can't just add a split for $35, because then the cash value of the transaction doesn't balance out. Now we have to introduce a bit of unpleasantness. We want that split for $35 from Income:Capital Gains, so to balance out the cash portion of the transaction, we create another split wherein we "purchase" 0 shares at $0 each, but spend $35 to do so:

Account                    Shares   Price    Debit    Credit
Assets:Broker:XYZ Inc      -5       $17.00            $85.00
Expenses:Broker Fees                         $7.00
Assets:Broker:Cash                           $78.00
Income:Capital Gains                                  $35.00
Assets:Broker:XYZ Inc      0        $0       $35.00

This last split exists to balance the capital gain split, but it has deeper meaning as well - it corrects the fundamental imbalance that was created by fluctuating exchange rates. In the upcoming (as of January 2006) 2.0 release, these splits will hopefully be created automatically, but it's certainly possible to enter them by hand in the 1.8 series of Gnucash.

More complicated situations can be resolved in a similar manner, though calculating the capital gains by hand could be wearisome (consider a mutual fund that has been seeing regular contributions for a long time, along with the occasional dividend reinvestment and maintenance fee, and consider only selling a portion of the currently owned shares). The Cash Flow Report and the Transaction Report can help you to calculate your cost basis, but that's beyond the scope of this question.

Version 2.x According to the thread https://lists.gnucash.org/pipermail/gnucash-user/2008-March/024501.html, it is possible to calculate capital gains on a lot basis in 2.x by following these steps:

1. Open the stock account's register.
2. Enter the sell transaction, with no splits for capital gains.
3. Select Actions->View Lots
4. Click Scrub Account.

See these mailing list messages (and other messages in these threads) for further reference:
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015605.html
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015620.html
https://lists.gnucash.org/pipermail/gnucash-user/2006-January/015396.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-July/014192.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-February/012863.html
https://lists.gnucash.org/pipermail/gnucash-user/2005-January/012648.html

Q: What is meant by year-end closing procedures?

A: Generally Accepted Accounting Practices include a procedure to "close" accounts at the end of a period (i.e., a fiscal year). This allows for the accumulated balances in an Income statement account (Revenue and Expense) to be pertinent to the current period only.

The procedure is to create an offsetting journal entry in each expense and revenue account that moves the balance of the account into a Retained Earnings account. (or, optionally, into the top "Revenue" or "Expense" account, and from there into the Retained Earnings account, reducing the number of periodic entries in the R/E account to 2 - one debit, and one credit)

The profit or loss incurred during a period, that is, the number calculated by the revenue accounts less the expense accounts, is represented in the Retained Earnings account entry for the period.

Customizing

Q: I'd like to write my own custom reports. Where should I start?

A: See Custom Reports.

In short, customizing reports requires some (small) knowledge of the programming language Scheme. Also, a customized report (e.g. the "multicolumn report") can be saved by clicking on the menu item "File -> Add report" (older versions: "Save report"), which will save the report into the file ~/.gnucash/saved-reports-2.0 so that it appears as a menu item at the next startup of gnucash. The saved reports will appear in the menu "Reports -> Custom".

Alternatively, each report can be created in a Scheme file in order to show up as a menu entry.

Q: How can I save my custom check printing configuration?

A: Currently, you cannot use the user interface to save your custom check printing definitions. If you are comfortable making a few simple edits to a scheme file, though, you can redefine one of the existing definitions to print correctly on your checks. To do this, first use the "print cheque" dialog box to add in your custom coordinates to get a check printed correctly. (Note that these dimensions count up from the lower-left of the check. Big numbers move the text up and to the right.)

Once you have the dimensions necessary to print correctly on one of your checks, you can edit the gnucash/scm/printing/print-check.scm file to change one of the existing definitions to print to your checks. The area that you need to change is labelled "stock-check-formats", and probably currently contains two format definitions. Change either one you like. Note that the dimensions defined here are not in the same order as those in the dialog box you were just working in. Now, you'll proabably have to restart gnucash for your new format definition to work.

To keep track of any progress to enhance this part of the application, check out the bugzilla bug 311062: http://bugzilla.gnome.org/show_bug.cgi?id=311062

Q: How do I save the options I have set on a built-in report as a custom report?

A: Run the report, edit the options as desired, and be sure to change the name of the report on the "General" tab of the options window. Report names must be unique. The "Add Report" entry in the "File" menu will be disabled until after you have changed the report name.

The report will be saved in the file C:\Users\%username%\.gnucash\saved-reports-2.4 (in case of Windows 7 installed on drive C:).

Developing GNUCash: Source Code Overview

Q: I heard it is too hard to compile GnuCash!

A: This was probably true at the time when 1.6.0 was released. It is no longer true today, as almost every distribution ships with all the necessary libraries. The easy way to do this on Linux is to use your package manager's build dependencies feature:

 apt-get build-dep gnucash
 yum-builddep gnucash
 zypper build-deps-install gnucash

The MacOSX/Quartz procedure for building on Macintosh OSX automatically builds all of the dependencies for you, as does the Windows procedure.

Q: Ok, what devel packages do I need in order to compile GnuCash?

A: The exact names of the required packages vary a bit depending upon the Linux distribution. Consult your package manager's dependency listing to find out -- then check Dependencies or the README.dependencies file after you check out the Gnucash source tree.

Q: Why is GnuCash written in C?

A: The core functionality of GnuCash is written in C, but do not forget that much of this can be accessed through Guile (scheme). There are a number of reasons for why GnuCash is written in C. The first is historical, Gnucash was started in 1996 (or maybe even earlier!) and many of the OOP (C++, Java, Python) compilers were not yet mature and standarized enough on the variety of platforms considered at that time, so C was the only option at that time. A second reason is because the standard GUI GnuCash uses is GTK, which is written in C.

Q: Why don't you rewrite GnuCash in programming language xyz so that I can contribute easily?

A: The quick answer is "We won't". The longer answer is complex but still amounts to "We won't". GnuCash is a large body of code maintained by a small group of developers who are comfortable in C and Scheme (Guile). Actually, 80% of it is in C and approx. 13% is in Scheme/Lisp. There is no valid reason that would justify rewriting this amount of existing code in a newer language.

Having said that, some kind folks have recently provided some python bindings to Gnucash. They are currently available only in trunk and not yet very mature. Stay tuned. Also, GnuCash is using SWIG for the Scheme language bindings [4] (new in version 2.1.0 and higher). These SWIG bindings can probably be adapted to include other languages into GnuCash without too much effort, but currently they are used only for Scheme bindings.

Q: Can I read the doxygen files documenting the API offline?

A: At first make sure Doxygen is installed on your machine. After you downloaded and configured (./autogen.sh ; ./configure ...) the GnuCash sources, you can call

make doc

and then you can open src/doc/html/index.html.

Q: Can I run GnuCash already in the build dir?

A: Usually you will run make install first and the run GnuCash. But you can also use "gnucash-build-env" to set up the right environment to run from the build dir. So you would need to run:

./src/bin/overrides/gnucash-build-env ./src/bin/gnucash

Q: How do I run GnuCash under gdb and get a stack trace?

A: See Stack Trace for instructions on running GnuCash under gdb to get a stack trace.

History

Q: Is the GnuCash team working on a gtk2 version?

A: GnuCash 2.0, the gtk2 version, was released on July 10th, 2006.

Q: What happened with Guppi when in the GnuCash 2.x version? Was it dropped?

A: Guppi was dropped completely in the GnuCash 2.x version. Its features are now being implemented by goffice. The gnucash-2.0.x tarball includes a copy of the goffice-0.0.4 source code. If gnucash's ./configure finds a newer goffice installed, it will use the installed goffice instead of the internal copy.

Q: I am having problems compiling g-wrap.

A: Specifically during configuring: "checking if guile long_long is at least as big as gint64... no checking if unsigned long is at least as big as guint32... no ./configure: exit: bad non-numeric arg `size'[[...]"