Next: , Previous: , Up: Units Conversion   [Contents][Index]

20 Updating Currency Exchange Rates and CPI

20.1 Currency Exchange Rates

The units program database includes currency exchange rates and prices for some precious metals. Of course, these values change over time, sometimes very rapidly, and units cannot provide real-time values. To update the exchange rates, run units_cur, which rewrites the file containing the currency rates, typically /var/lib/units/currency.units or /usr/local/com/units/currency.units on a Unix-like system or C:\Program Files (x86)\GNU\units\definitions.units on a Windows system.

This program requires Python 3 ( The program must be run with suitable permissions to write the file. To keep the rates updated automatically, run it using a cron job on a Unix-like system, or a similar scheduling program on a different system.

Reliable free sources of currency exchange rates have been annoyingly ephemeral. The program currently supports several sources:

The default source is FloatRates; you can select a different one using -s option described below.

Precious metals pricing is obtained from Packetizer ( This site updates once per day.

20.2 US Consumer Price Index

The units program includes the US Consumer Price Index (CPI) published by the US Bureau of Labor Statistics: specifically, the Consumer Price Index for All Urban Consumers (CPI-U), Series CUUR0000SA0. The units_cur command updates the CPI and saves the result in cpi.units in the same location as currency.units. The data are obtained via the BLS Public Data API ( This data updates once a month. When units_cur runs it will only attempt to update the CPI data if the current CPI data file is from a previous month, or if the current date is after the 18th of the month.

20.3 Invoking units_cur

You invoke units_cur like this:

units_cur [options] [currency_file] [cpi_file]

By default, the output is written to the default currency and CPI files described above; this is usually what you want, because this is where units looks for the files. If you wish, you can specify different filenames on the command line and units_cur will write the data to those files. If you give ‘-’ for a file it will write to standard output.

The following options are available:


Print a summary of the options for units_cur.


Print the units_cur version number.


Give slightly more verbose output when attempting to update currency exchange rates.

-s source
--source source

Specify the source for currency exchange rates; currently supported values are ‘floatrates’ (for FloatRates), ‘eubank’ (for the European Central Bank), ‘fixer’ (for Fixer), and ‘openexchangerates’ (for open exchange rates); the last two require an API key to be given with the -k option.

-b base
--base base

Set the base currency (when allowed by the site providing the data). base should be a 3-letter ISO currency code, e.g., ‘USD’. The specified currency will be the primitive currency unit used by units. You may find it convenient to specify your local currency. Conversions may be more accurate and you will be able to convert to your currency by simply hitting Enter at the ‘You want: prompt. This option is ignored if the source does not allow specifying the base currency. (Currently only floatrates supports this option.)

-k key
--key key

Set the API key to key for currency sources that require it.

--blskey BLSkey

Set the US Bureau of Labor Statistics (BLS) key for fetching CPI data. Without a BLS key you should be able to fetch the CPI data exactly one time per day. If you want to use a key you must request a personal key from BLS.

Next: Database Command Syntax, Previous: Readline Support, Up: Units Conversion   [Contents][Index]