GnuCash  5.6-150-g038405b370+
Python bindings

Also have a look at group Python Bindings Module.

In the source tree they are located at bindings/python.

To enable them in the compilation process you have to add -DWITH_PYTHON=ON to the call of cmake.

As a starting point have a look at the example-scripts.

What can Python Bindings be used for ?

The python bindings supply the ability to access a wide range of the core functions of GnuCash. You can read and write Transactions, Commodities, Lots, access the business stuff... You gain the ability to manipulate your financial data with a flexible scripting language.

Not everything GnuCash can is possible to access though. The bindings focus on basic accounting functions. Have a look at the examples to get an impression.

Some functions are broken because they have not been wrapped properly. They may crash the program or return unaccessible values. Please file a bug report if you find one to help support the development process.


The python-bindings are generated using SWIG from parts of the source-files of GnuCash.

Python-scripts should not be executed while GnuCash runs. GnuCash is designed as a single user application with only one program accessing the data at one time. You can force your access but that may corrupt data. Maybe one day that may change but for the moment there is no active development on that.

What SWIG does

SWIG extracts information from the c-sources and provides access to the structures to python. It's work is controlled by interface files :

it outputs:

If you have generated your own local doxygen documentation (by "make doc") after having compiled the python-bindings, doxygen will include SWIGs output-files. It's actually quite interesting to have a look at them through doxygen, because they contain all that you can access from python.

This c-style-api is the bottom layer. It is a quite raw extract and close to the original source. Some more details are described further down.

For some parts there is a second layer of a nice pythonic interface. It is declared in

How to use the Python bindings

High level python wrapper classes

If you

>> import gnucash

You can access the structures of the high level api. For Example you get a Session object by

>> session=gnucash.Session()

Here you will find easy to use things. But sometimes - and at the current level rather sooner than later - you may be forced to search for solutions at the :


If you

>> import gnucash

The c-style-api can be accessed via gnucash.gnucash_core_c. You can have a look at all the possibilities at

You will find a lot of pointers here which you can just ignore if input and output of the function have the same type.

For example you could start a session by gnucash.gnucash_core_c.qof_session_begin(). But if you just try


you will get an error message and realize the lack of convenience for you have to add the correct function parameters.

Not all of the available structures will work. SWIG just takes everything from the sources that it is fed with and translates it. Not everything is a working translation, because not everything has been worked through. At this point you are getting closer to the developers who you can contact at the mailing-list There may be a workaround. Maybe the problem can only be fixed by changing SWIGs input files to correctly translate the c-source. Feel free to post a question at the developers list. It may awaken the interest of someone who creates some more beautiful python-interfaces.

When to use which api ?

The start would surely be the high-level api for you can be quite sure to have something working and you will maybe find explanations in the example-scripts. If you search for something that is not yet implemented in that way you will have to take your way to the c-style-api.

(Further) documentation


Christoph Holtermann
December 2010