|Back to: Using GnuCash||german version|
GnuCash can automatically retrieve the current share price of marketable commodities (e.g., stocks, mutual funds, currency exchange rates), called a quote, so that you do not need to manually update the prices of these securities in the GnuCash Price Database one at a time. If you are tracking the prices of more than a handful of securities, this features saves an enormous amount of time.
- 1 Overview
- 2 Setting up online quotes in GnuCash
- 3 Helper Scripts
- 4 Requirements
- 4.1 Perl
- 4.2 Finance::Quote
- 5 Finding the right Source and Symbol
- 6 Updating enabled Quotes from outside GnuCash
- 7 Technical Details
- 8 Documentation
GnuCash stores the share prices of investments in the respective buy/sell/split transactions and additional quotes in an internal price database. Although it is possible to enter prices manually into the price database, it is more convenient to update them from online sources. GnuCash uses an external program written in the Perl programming language called Finance::Quote (often shortened to simply F::Q) to fetch these quotes online. Therefore, for this feature of GnuCash to work, your computer will need to have some additional software installed beyond simply the GnuCash application itself, as well as have an active Internet connection.
The Finance::Quote Perl module is managed at
- CPAN (both recent), and
- SourceForge (hopeless outdated, last news: 2015-Aug-22 Release 1.38).
Since the Finance::Quote software is not part of GnuCash proper, if you believe you have found a bug in the Finance::Quote module, there is probably not a lot the GnuCash developers can do to fix the problem for you. Instead, you should report the issue directly to the Finance::Quote developers at the following bugtrackers:
- http://rt.cpan.org/Public/Dist/Display.html?Status=Active&Name=Finance-Quote and
However, please be reasonably confident that the problem truly lies in the Finance::Quote software and not somewhere else (e.g., could your Internet connection simply be down right now?) before you submit a bug report to the Finance::Quote developers.
The Finance::Quote software gathers its price data from several Web sites around the world that provide this information in different ways. Some sources offer
- an API like JSON or YQL,
- downloads, usually as CSV file, and finally
- quite literally by extracting information from the web page itself.
As these sources change frequently, we advise you to keep Finance::Quote up-to-date. (See below for instructions.)
Setting up online quotes in GnuCash
The GnuCash Help includes instructions on setting up online quotes. This set up procedure provides the input to Finance::Quote, so it must be completed before the "Get Quotes" button in GnuCash's Price Database will have any effect.
Once again, Finance::Quote is external to GnuCash. Thus, for it to work, you need some additional installed. This includes the Perl interpreter itself, the Finance::Quote module, and the dependencies for this software. Occasionally, you will need to update Finance::Quote (and possibly, more occasionally, Perl) separately from GnuCash.
To ease this update process, the GnuCash developers provide several helper scripts.
For your convenience, we ship a bunch of gnc-fq-* programs, which again are Perl scripts:
- returns the version number and the list of available F::Q modules,
- installs or updates F::Q and its dependencies, if Perl is already installed;
- returns data for a source and a list of symbols,
- a filter, which does the same, but in- and output are Scheme expressions.
You might use them for troubleshooting, if Gnucash fails to update quotes.
F::Q relies on Perl, which must be installed. Perl is handled differently on the different operating systems.
- Unix (Linux, AIX, *BSD, HPUX, Solaris,...): Perl is probably already installed or gets installed as dependency, if you install Finance::Quote by your systems package manager. Run
perl -von a command line to get the version number. If that fails, use your package manager to install it.
- Mac OS X: Perl is already installed. Open a Terminal application (in the Utilities folder of your Applications folder) and run
perl -vto see the version number.
- Windows: <to be moved from Windows#Finance::Quote etc.>
- While unixoid operating systems use a shebang
#!to associate perl scripts with the perl interpreter, others might fail. So, if you get an error like
gnc-fq-check is not recognized as an internal or external command, operable program or batch file
- you should repeat the command with a preceeding perl:
As mentioned previously, Finance::Quote is a Perl module that must be installed to enable online quote fetching. Finance::Quote, in turn, depends on a number of other Perl modules.
You can check the version and the list of available modules by running
from the command line.
Installing or Updating
The easiest way to install the Finance::Quote software needed for retrieving price quotes for securities from online sources in GnuCash is to use the provided installation tools, or your system's package manager. Both the Microsoft Windows and macOS GnuCash packages include provided update tools for Finance::Quote, while many Linux distributions provide a standard way to install packages (e.g., the
apt program on Debian-based Linux distributions and the
dnf tool on RedHat-based Linux distrubtions such as Fedora).
Installing Finance::Quote on Windows
On a Microsoft Windows computer, GnuCash provides the
Install Online Price Retrieval program, which is located in the GnuCash group in the Start Menu. Simply click on it to begin the Finance::Quote installation process. You can re-run the
Install Online Price Retrieval program as often as you like to ensure the Finance::Quote module remains up to date.
Installing Finance::Quote on macOS
On a macOS computer, GnuCash provides the
FinanceQuote Update app, which is located in the disk image (
.dmg file) along with the main GnuCash app itself. When you install GnuCash by dragging and dropping the GnuCash app icon to a location on your computer's hard drive (like your
Applications folder), you should also consider installing the
FinanceQuote Update app into the same folder as you installed the main GnuCash app.
FinanceQuote Update app by double-clicking it to begin the Finance::Quote installation process. You can re-run the
FinanceQuote Update app program as often as you like to ensure the Finance::Quote module remains up to date.
Installing Finance::Quote on macOS from a Terminal prompt
FinanceQuote Update app is a very simple AppleScript Applet that runs a command equivalent to the following in a Terminal:
FinanceQuote Update applet fails, you can simply run the above command while logged in to a user account with administrative privileges. (Note that a mere
su may not be sufficient; you should log out of all user accounts, then log in as the admin user for the computer on which you want to install Finance::Quote, then run the above command from a Terminal.)
As with the applet, you can re-run the command as often as you like to ensure the Finance::Quote module remains up to date.
Installing Finance::Quote on Linux
On a Linux computer, the recommended way to install Finance::Quote is by searching in your OS distribution's package manager for
finance-quote. Note that your distribution's package maintainer may prefix the package name with perl, lib, or both. We also recommend that you check the version of Finance::Quote offered by your OS package repositories to ensure it is a recent-enough version.
If no recent version of the Finance::Quote module is offered by your package manager, you should run the
gnc-fq-update helper script manually. As
root (using the
su and/or the
sudo commands) run the GnuCash Finance Quote update script:
This will begin the installation procedure for Finance::Quote and all of its dependencies.
- Note for (Ubuntu based) distributions
- Some of them removed it from the package. In this case you can
- download it from github e.g. into your personal ~/bin directory,
- In the first line replace @-PERL-@ with the path to your perl executable, e.g., /usr/bin/perl, remove the trailing .in from its name and mark the file as executable.
- A discussion of how to fix it in Ubuntu can be found at .
Since GnuCash version 2.6.12, this helper script uses CPAN (see the next section) to install the following Perl modules:
- and their dependencies
Installing Finance::Quote using CPAN
CPAN is the Comprehensive Perl Archive Network, which provides a collection of free Perl software (called modules) from which you can obtain the perl Finance::Quote module along with all of its dependencies. If the methods listed above for your specific Operating System distribution fails, you may nevertheless be able to install Finance::Quote by directly interfacing with CPAN yourself.
To do so using CPAN:
perl -MCPAN -e shell # Either, if F::Q is missing, install it with install Finance::Quote # or, if F::Q is outdated, update it with upgrade Finance::Quote # finally check for Date::Manip install Date::Manip # and exit: q
- On the first run of
cpanit needs some configuration:
CPAN.pm requires configuration, but most of it can be done automatically. If you answer 'no' below, you will enter an interactive dialog for each configuration option instead. Would you like to configure as much as possible automatically? [yes]
- It is usually save to accept the defaults.
- FAQ#Q: How do I install Finance::Quote on a Mac?
- FAQ#Q: How do I fix a "system error" or "unknown error" when getting stock quotes?
Finding the right Source and Symbol
Because not all sources offer all commodities and different sources use different symbols, it is the high art to find the right combination. Common symbols are:
- Ticker symbols: 1-4 character abbreviation of company names, often used for US shares;
- National Security Identification Numbers: like CUSIP, often used by national fund companies;
- ISIN: International Security Identification Numbers, at least in the EU they are more and more replacing the different NSINs;
- sometimes completed by an appendix indicating the market place.
gnc-fq-dump -v <Source> <Symbol>
If your commodity is a mutual fund and F::Q offers its fund company as source (deka, dws, ...) look on their website, which symbols they use and you are done.
Is there a source for its registered exchange (AEX, ASX, ...) do the same.
In other cases google the ISIN to get a list of possible sources.
Global players: Alphavantage and Yahoo* are stronger in shares and Morningstar* in funds.
Updating enabled Quotes from outside GnuCash
You can run
gnucash --add-price-quotes /path/to/file.gnucash
or on macOS™:
/Applications/Gnucash.app/Contents/MacOS/Gnucash --add-price-quotes /Users/<username>/Documents/test.gnucash
to update all enabled quotes.
N.B.: On Microsoft Windows™ if the path includes a disk letter then you must pass a file URI or GnuCash will confuse the drive letter for a URI scheme and fail to open it. e.g.:
Warning About Open Files
Updating quotes will modify the GNUCash file/database. As multi-user access is not supported, the file/database should be closed prior to updating quotes.
Cron and Non-X Usage
GConf Error: Failed to contact configuration server; the most common cause is a missing or misconfigured D-Bus session bus daemon. See http://projects.gnome.org/gconf/ for information. (Details - 1: Not running within active session)
One resolution for this, courtesy of SyncEvolution - The Missing Link, is to launch dbus for the duration of the quote retrieval with a cron command similar to:
env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT; gnucash --add-price-quotes /path/to/file.gnucash'
Note: This has been documented in Bug #639776.
Where the F::Q files are stored depends on your OS/Distro:
- Linux depends on the way it was installed:
- by package manager: /usr/share/perl5/[vendor/]Finance/Quote
- by CPAN or gnc-fq-update: /usr/share/perl5/site/Finance/Quote
- self compiled: /usr/local/share/perl/5.xx.x/Finance/Quote
- Windows: C:\Perl\site\lib\Finance\Quote
You can get the path by running:
perldoc -lm Finance::Quote
(Tested on Linux and macOS. Please update for Windows.)