From GnuCash
Revision as of 14:46, 31 January 2008 by Vinci (talk | contribs) (GnuCash Files and managing a GnuCash installation)
Jump to: navigation, search

The contents of this FAQ will eventually be merged into the GnuCash help documentation. Or maybe not.


General Frequently Asked Questions (FAQ) about GnuCash

Q: How can I contribute to the GnuCash project?

A: Further answers about this are on the Development 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.

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

A: The Development wiki page has information about how you can donate to the GnuCash project. We appreciate your support.

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

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

  1. The user interface itself.
  2. Statements printed to the terminal from which gnucash was run.
  3. The log file:
    1. Linux/BSD/*nix: /tmp/gnucash.trace
    2. Windows: c:\Documents and Settings\myname\Local Settings\Temp\gnucash.trace.XXXXX
    3. Vista: C:\Users\myname\AppData\Local\Temp\gnucash.trace.XXXXX

In order to get more detail, open a Terminal from your system menu, and start gnucash at the prompt; this is almost always done by typing simply "gnucash" at the prompt. Save the detail emitted to the terminal (if any), as well as the contents of the /tmp/gnucash.trace file.

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 Development 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. Please bear in mind to describe your proposed enhancement as verbosely as possible. The trick here is to learn how to give the best information to the programmers about what your proposed new feature should do. If you want to speed up development significantly, consider donating some money as described on Development.
Note that the fastest way to get a feature added is to implement it yourself. A bug report with an attached patch is very likely to get applied quickly.
See also: WishList

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>
(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 on Windows. Until then, the Windows releases are still in development and some unstable versions are available.
See Windows for more recent details regarding the windows port.
Other related options would be colinux, VMWare 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#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). No extra uninstall of the older version is needed.
There is one exception from this rule: If you want to install GnuCash version 2.2.0, but have one of 2.1.5 or older already installed, then: No, in this particular case you have to uninstall the old version first before installing the new version because several changes to the installer system were made between 2.1.5 and 2.2.0.
For all other cases (i.e. updating from 2.2.0 to 2.2.1 and so on): Yes, you can install the newer windows binary (say, 2.1.5) directly on top of the older one (say, 2.1.4). No extra uninstall of the older version is needed. There is no problem with that.

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

A: This is caused by a fundamental technical fault of the MS Windows operating system. Gnucash depends on approx. 50 other DLLs. We don't know whether any of those happen to exist already in your windows/system32 folder. If they did, the are probably vitally important for some other application on your computer and must not be replaced by the version that is required by and shipped with gnucash. If gnucash had overwritten an existing DLL in your windows folder, this would have killed that other application. This should better be avoided, and on MS Windows the only possible way to really avoid crashing your other existing application unfortunately requires shipping our own DLL into our own Program folder of gnucash. That's the reason.
(On Unix, this is solved by choosing filenames for the DLLs that contain the exact version number, like so: libglib-2.0.so.0.1200.4. That way, a DLL with a different version will always be a different file and doesn't silently overwrite an existing DLL with another version.)

GnuCash 2.0.x Troubleshooting

Q: How do I change the register colors?

A: See https://lists.gnucash.org/pipermail/gnucash-user/2006-February/015941.html

Q: Why did Finance::Quote stop working?

A: You need to install the Crypt::SSLeay perl module. This is a requirement inherited from the latest version of F::Q, version 1.12.

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.

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: 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.11 version or later. Earlier versions can no longer retrieve currency quotes.
  2. Run the command gnc-fq-check from the command line. The output should look like ("1.11" "tsp" "vwd" .....). If it doesn't follow the directions to install any missing libraries.
  3. 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"))). 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.
  4. 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.

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.
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: 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: How to install on Mac OSX?

Also visit the MacOSXInstallation page that the developers seem to update somewhat regularly.
A:I installed Gnucash without problems on a new machine with OSX 10.3.4.
  1. X11 is installed from Panther discs.
  2. I installed fink from the binary distribution Fink-0.7.0-Installer.dmg
  3. I installed finkcommander from the above distribution
  4. I upgraded finkcommander per instructions
  5. I ran Source->Selfupdate-rsync (not sure whether this was strictly necessary)
  6. I selected gnucash and ran Binary->Install
  7. Started X11
  8. Applications->Customise->Add Item Name=gnucash Command=/sw/bin/gnucash
  9. Start guncash either from pulldown or by typing guncash in xterm. In xterm error messages are displayed whereas they seem to be suppressed using the Application menu.
  10. If in not in US Edit->Preferences->International select and apply your money and your dates scheme.
  11. Enjoy
A2: Here's another method:
  1. Make sure X11 (XDarwin), X11SDK, Fink, and !FinkCommander are installed and working.
  2. Check the 'Use unstable packages' box in the !FinkCommander Preferences. That will display gnucash in the table.
  3. Select gnucash from the table and click the 'Install package(s) from source' button. Fink will check for dependencies and provide a list of programs & libraries that need to be installed.
  4. If you have more than 3 or 4 that need to be installed, write the list down and install each individually or in small groups. Fink gets confused with large lists of dependencies. Some items may take a while to download and/or install. If download or personal time is limited, you can stop in the middle and come back at a later time. Once the programs & libraries are installed, you don't have to re-install them later.
  5. After installing all the dependencies, select gnucash again and click the 'Install package(s) from source' button. This may also take a while to download and/or install.
  6. Open X11 and in an X11 terminal, start gnucash by typing gnucash<enter>. If gnucash does not start, copy any errors that are printed to the screen and either correct the problem(s) or submit them to the !GnuCash User list at [1] and someone will try to help you.
  7. After starting gnucash from the command line a few times and making sure there are no errors, install the !GnuCash Launcher applet from [ here | http://homepage.mac.com/elliottmce/gnucash_guide/Page005.html]. It's an easy way to start the gnucash application after you have it working from the command line. Just remember that if you are having problems starting the program to try launching from the command line to see any errors that are being generated.

Workaround for "dlcompat" error on launch:
The following note on the fink mailing list from Martin Costabel solved my problem at launch (same as Jamie's): {reproduced without permission...}

From: Martin Costabel <costabel@wa...>
Re: gnucash (binary) problems on Fink 0.7.1  
2004-09-24 16:44

Jamie Caplan wrote:

> loading library: /sw/lib/libbonobox.2.dylib
> loading library: /sw/lib/libbonobo.2.dylib
> ERROR: In procedure dynamic-link:
> ERROR: file: "libgw-gnc", message: "dlcompat: invalid handle"

The next one to load would have been libgtkhtml.20.dylib. Do you have
the package gtkhtml-shlibs installed? {Re}install it.
A3: See also: http://homepage.mac.com/elliottmce/gnucash_guide/
A4: See http://captnswing.net/2006/07/10/gnucash20_on_intel_macs.html if you have an Intel Mac

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?

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 SVN 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?

A: 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.

GnuCash Files and managing a GnuCash installation

Q: What's the gnucash file extension?

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)
  • .gnc (the "internal" three-letter-abbreviation of GnuCash)
  • .gnucash (recommended)

Q: Where is my .XML data file?

A: It's the file you are using - the one that you named when you created the new file to hold your accounts. Note that it might be gzip-compressed although it doesn't have an extra ".gz" extension.
The data file is called whatever name you specified at your first "Save as..." operation. GnuCash doesn't force any particular file name extension, so depending on your own choice the XML data file might end with ".gn2", ".xac", ".xml", ".whatever", or even no extension at all.
If you forgot the name of the actual data file (although it should be displayed in the window title of your GnuCash window), you can do the following: In GnuCash, press "Save", then "File -> Quit". The actual data file will be that one in the data file directory which was last changed.

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.

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

A: These are backup data files (".xac") 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.

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

Other Solutions:

Q: I'm running gnucash under 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: How do I backup my GC environment, including preferences?

A: Make sure you save not only all your .xac, .log files and the actual ledger file, but also $HOME/.gnucash, $HOME/.gnome/GnuCash, and $HOME/.gnome/accels/GnuCash.

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.

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: Somehow I managed to close the account view tab. How can I get it back?

A: A new account view tab can be opened with File -> New -> New Accounts Page.

Q: Is there a database backend?

Q: Is the Postgres DB / SQL backend supported?

A: A postgres/SQL 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.

The postgres backend has been considered obsolete by the core developers since the 2.0 release. Since 2006, there is a development branch to create a GDA-based backend to replace the postgres-specific backend. While in mid-2007, progress on this branch had been slow, in early 2008, progress on this branch has picked up some momentum. The most up to date status can be found by consulting the archives of the gnucash-devel mailing list; your help is welcome!

See also: Bug 90375.

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

A: Especially since the SQL backend doesn't support the business features, which is usually the driving desire for multi-user support, the only recommended multi-user setup right now is through a shared file. 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.

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

Not quite. You can always upgrade from versions >= 1.8 to a higher version number (yet true for 2.2.3). You can read 2.0 in 1.8.x fine. Reading 2.2 in 2.0 will not work if you have scheduled transactions.

Questions about Using GnuCash

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: 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: Is there book-closing support, yet?

A: There is some support in SVN, and we're curious to hear your feedback about it. A not-unreasonable work around is to copy your data file, and edit it to add zeroing transactions to each income/expense account. Also note that the reports should be able to provide accurate data even without zeroing transactions, so your P&L and Balance Sheet reports will still work. However your account balances won't show year-to-date.

Other methods:

  • One File Per Year At the end of each year you can start a new GnuCash file for the next year. The easiest way to do this and start with all your old account names is to use File->Export->Accounts. Give it the name you intend to use for the new year. Then do File->Open and select the name you just saved. You will need to transfer over your starting balances, but at least the account names are there.
  • 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 "2005 Year End". 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 2005 Year End account. The account report for the "2005 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 had 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.

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

A: In lieu of formal documentation, see the following:

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: no answer yet

Q: I exercised ISOs 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!!!

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.

Importing/Exporting Data

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: 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.)
There is also http://gnucashtoqif.sourceforge.net/ which is a Java program that can transform a gnucash XML file to a QIF file.
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.
There exist some scripts to move gnucash data into a mysql database.

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

A: gnucash --help will show any available commands for executing scheme, but you will likely have to write a good chunk of code to be invoked this way to import the data.
Probably a saner course of action is to convert the external transactions into a shared format such as QIF or OFX and import them using the existing application functionality.

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.tiscali.fr/calc2qif_en.php.

Jeroen van der Vegt has changed the csv2qif by Baruch Even for the (Dutch) Rabobank asc files. It can be dowloaded at http://gnucash.camfree.nl/rabocsv2qif (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.

Q: My bank doesn't offer OCX 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."

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: 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.

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 it looks blank then click anywhere in the register and the transactions will magically appear. Hopefully someone will fix this bug soon, but for now its just an annoyance.
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.

Using Business Features

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

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

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.
  • 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: 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"))

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

A: First, create one of the sets of accounts listed below, and the associated Tax Table (see Business => Tax Tables menu).

Description 3-account Naming scheme 4-account naming scheme Tax table
Claimable GST you have paid on purchases Liabilities:GST:Paid Liabilities:Taxes:GST
GST amounts you have collected from customers Liabilities:GST:Payable
GST you have charged/invoiced to customers Assets:Accounts Receivable:GST GST
GST amounts you have paid to the government Liabilities:GST:Payments Tax Expenses:Taxes:GST
GST amounts that have been deferred Liabilities:Taxes:GST:Deferred

There is also an Alternate Australian GST setup that might make more sense to you.

Directions for 3-account naming scheme

GST for accounts payable is easy. Just select GST as your tax table for each transaction. This should automatically add the GST amount to the Liabilities::GST::Payable account.
For GST for purchases, we need to create a split transaction. Say you are entering the transaction in your Cash account. Enter the total amount in the spend column, including GST, then hit the split button. You'll see a balancing debit in the receive column. Allocate this to the appropriate account, but decrease the amount to the cost before GST. You will then see a new debit line, with the GST amount in the receive column. Allocate this to Liabilities:GST:Paid account. This will show in this account as a negative amount, that is, as a rebate.
Then, whenever you pay your GST amounts to the government, enter this in Liabilities:GST:Payments.

Directions for 4-account naming scheme

The following are things to note for the four-account naming scheme:

  • Using the Transaction Journal view (This can be set as your default in Preferences). All of the following processes assume that you are using this type of transaction log, and ask you to use the one transaction to perform operations on various accounts.
  • Not necessary, but recommended is full set of business accounts (of which I use the names here)
  • Also, this scheme was designed by someone who understands computers, but not necessarily accounting. But it works for me :). None of it should be construed as tax advice; if you want that, see an accountant or something
  • The Deferred stuff isn't mentioned in the processes below, but I'm told it's necessary for anyone deferring tax. Enjoy.

The following are directions for the processes you may follow:

  • Invoices: Just select "GST" as your tax table for each transaction
  • Payments (from customers): When receiving the payment, reduce the Assets:Accounts Receivable:GST by the GST amount, and increase Liabilities:Taxes:GST by the same amount
  • Purchases: In your split transaction, transfer the non-GST amount from eg. your Assets:Current Assets:Savings Account, and the GST amount from your Liabilities:Taxes:GST account, placing the full amount in the appropriate expenses account
  • Filling in your GST form: The amount you put in should be the current amount on Liabilities:Taxes:GST. Make a note of any rounding amount (ie. cents) as you'll need it in the next process
  • Paying your GST: When you pay the GST, transfer the amount that you paid from Liabilities:Taxes:GST to Tax Expenses:Taxes:GST. If there was a rounding amount that you were required to exclude from your BAS form, transfer it to eg. Assets:Current Assets:Savings Account as part of this transaction (making a note that it's the rounding, so if you're getting audited, there's an explanation).

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

A: No. There are some basic business template accounts (for 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.

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: 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.

Accounting Questions

Q: Can you recommend a book on Accounting?



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

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 book-keeper, add your name and contact info here.

New York City: Mark Bartosh, CPA cell (646)660-2807 e-mail: darwin3141@excite.com Raleigh, North Carolina - Kenneth M. McNees, CPA, CISSP, CISA, CAP, CISM. kennymcnees@gmail.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:

    XYZ Inc
  Broker Fees
  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.

See these mailing list messages (and other messages in these threads) for further reference:

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.


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" button will be disabled until after you have changed the report name.

Questions about GnuCash Localization (L10n) and Internationalization (I18n)

Q: I want to use GnuCash in my own language (Debian users may need it)

A: You have to set: "env LANGUAGE=fr_FR" and "env LANG=fr_FR". This example is for french (français) and then launch GnuCash.
For Debian users: make sure your locales are properly installed. If not, run 'dpkg-reconfigure locales'. Note that the default desktop manager for Debian is GDM which does NOT read the .xsession files. To get the right language using GDM, use the Options button on the GDM login screen and set the default language. (The list includes all those languages supported by locales). When you login, confirm that the new language is to be the default for future sessions.
German users could add the following line to the start-menu: "env LANG=de_DE gnucash %f" or type the command in the terminal on one line!
On some systems, the encoding could be part of the locales name, like "env LANG=no_NO.UTF-8 gnucash %f".

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".

Developing GNUCash: Source Code Overview

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

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

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 (except g-wrap, which means there is in fact one extra library to be installed before compiling GnuCash). However, by default, distributions won't install the development packages of the required libraries, so you might need to start your distribution's installer program and tell it to install not only the library packages but also the -devel packages. In general, it was noted that this problem concerns many applications in the gnome domain, and this also boils down to the fact that there is no such thing as one monolithic gnome package.

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

A: The exact names of the required packages vary a bit from distribution to distribution. For example, for an rpm-based distribution, you'll typically need at least: g-wrap-devel >= 1.3.4, gtkhtml-devel >= 0.8, Guppi-devel, gal-devel, libxml-devel, libglade-devel, libghttp-devel, python-devel, libtermcap-devel, readline-devel, and (optionally) post-gresql-devel. For more details see the Dependencies section of the README file.

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. Also, creating language bindings to recent languages such as Python or Ruby or (insert your favourite language here) is labour intensive, and we're already stretched pretty thin maintaining and developing the existing code.
Having said that, this is an open source project and you're free to do with it or contribute what you want. Just don't expect much support if the reason for your changes is that you're not willing to learn C or Scheme. Also, GnuCash is using SWIG for the Scheme language bindings [2] (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: 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.

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'[[...]"

A: Try configuring guile to build with thread support (./configure --with-threads).
Also, g-wrap won't be needed from gnucash-2.1.0 onwards anymore. Neither the currently used swig nor the previously used g-wrap packages are needed anymore when compiling from tarball or when installing a binary. (Only when compiling from SVN you need swig installed.)

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.


a tool for the automated generation of source code documentation. doxygen.org says that "Doxygen is a documentation system for C++, C, Java, IDL (Corba and Microsoft flavors) and to some extent PHP and C#."
stands for "Generally Accepted Accounting Principles", the rules by which Business Accounting has to be done, especially in the U.S. and some other countries.
a tool for creating Scheme interfaces to C libraries and vice versa. (Not being used for SVN-trunk and gnucash >= 2.2.0 anymore.)
the GIMP Tool Kit. It is the underlying graphical library that is used by GIMP but also by the whole Gnome desktop. gtk.org says that "GTK+ is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off projects to complete application suites."
is an interpreter for the Scheme programming language, packaged as a library which can be incorporated into your programs. Other interpreters for Scheme are e.g. MIT Scheme, UMB Scheme, Luna, Hobbit, and many others.
a GNOME-based framework for graphing and interactive data analysis. This library created the pie charts and bar charts in GnuCash. Unfortunately, its development has been abandoned.
a bank-independent online banking protocol used by German banks. HBCI (Home Banking Computer Interface) has been developed by the German Central Banking Committee ZKA (Zentraler Kredit-Ausschuss). The standard is publicly available and is used by approx. 50% of German banks, but nowhere else in this world.
an Open Source library for OFX (see below). It was created by one of the GnuCash developers (Benoit Gregoire), originally to be the OFX interface for GnuCash.
a financial information standard defined by SWIFT and used by several European banks. It is also used internally in HBCI. Unfortunately, you can't download the MT940 standard, but some banks (like this one) publish it on their web site.
the Open Financial eXchange format. This is a financial information standard (i.e. a file format standard) documented at http://www.ofx.net/ofx/default.asp
an Open Source implementation of the German HBCI.
a functional programming language, a dialect of Lisp. There's a little more information at http://www.swiss.ai.mit.edu/projects/scheme/, where they'll tell you that "Scheme is a statically scoped and properly tail-recursive dialect of the Lisp programming language invented by Guy Lewis Steele Jr. and Gerald Jay Sussman."