forex-python

1.9.2 · active · verified Tue Apr 14

forex-python (version 1.9.2) is an active Python library providing free foreign exchange rates and currency conversion functionalities. It supports listing all currency rates, retrieving Bitcoin prices, converting amounts between currencies, and accessing historical rates since 1999. The library's core data comes from theratesapi.com (sourced from the European Central Bank) for currency rates and CoinDesk for Bitcoin prices. It is regularly updated, though with an irregular release cadence, and is compatible with Python versions >=2.7 and <4, excluding 3.0-3.2.

Warnings

breaking The underlying API source used by `forex-python` has changed multiple times (e.g., to ratesapi.io in v1.0.0, and currently theratesapi.com). Older versions (especially pre-1.6) are prone to `RatesNotAvailableError` due to these upstream API changes or intermittent issues. Always use `forex-python>=1.6` to mitigate these issues and ensure compatibility with the current API.
Fix: Upgrade to the latest version of `forex-python` (e.g., `pip install --upgrade forex-python`).
gotcha By default, `forex-python` might return floating-point numbers for exchange rates and converted amounts, which can lead to precision errors in financial calculations. For accuracy, especially with monetary values, initialize `CurrencyRates` and `BtcConverter` with `force_decimal=True` and perform calculations using Python's `decimal.Decimal` type. This feature was introduced in version `0.3.2`.
Fix: Initialize `CurrencyRates(force_decimal=True)` or `BtcConverter(force_decimal=True)` and use `decimal.Decimal` for amounts.
gotcha The currency exchange rates provided by `forex-python` are updated daily around 3 PM CET, as they are sourced from the European Central Bank. This means the rates are not 'real-time' in a sub-second or minute-by-minute sense, but rather daily snapshots. Users requiring instant, live exchange rates should consider dedicated real-time forex APIs.
Fix: Understand that rates are daily, not live. For intra-day real-time data, use a different library or API service.
gotcha There have been user reports and GitHub issues regarding missing currencies or occasional discrepancies and incorrect conversion rates for specific currency pairs (e.g., AED, GBP to INR). While generally reliable, for critical applications, cross-validation with another source is advisable.
Fix: For critical applications, cross-verify rates with an alternative data source, especially for less common currency pairs or if discrepancies are observed.

Install

pip install forex-python Install stable version

Imports

CurrencyRates

from forex_python.converter import CurrencyRates

BtcConverter

from forex_python.bitcoin import BtcConverter

CurrencyCodes

from forex_python.converter import CurrencyCodes

Quickstart

This quickstart demonstrates how to fetch current exchange rates, convert amounts, get Bitcoin prices, and retrieve currency symbols using the `forex-python` library. It emphasizes using `force_decimal=True` for accurate financial calculations.

from decimal import Decimal
from forex_python.converter import CurrencyRates, CurrencyCodes
from forex_python.bitcoin import BtcConverter

# Initialize CurrencyRates with force_decimal for precision
c = CurrencyRates(force_decimal=True)

# Get conversion rate from USD to INR
usd_to_inr_rate = c.get_rate('USD', 'INR')
print(f"1 USD = {usd_to_inr_rate} INR")

# Convert an amount
amount_usd = Decimal('100.50')
converted_amount_inr = c.convert('USD', 'INR', amount_usd)
print(f"{amount_usd} USD = {converted_amount_inr} INR")

# Get all latest rates for a base currency
all_usd_rates = c.get_rates('USD')
# print(f"All USD rates: {all_usd_rates}") # Uncomment to see all rates

# Get Bitcoin price
b = BtcConverter(force_decimal=True)
btc_usd_price = b.get_latest_price('USD')
print(f"1 BTC = {btc_usd_price} USD")

# Get currency symbol
codes = CurrencyCodes()
gbp_symbol = codes.get_symbol('GBP')
print(f"GBP symbol: {gbp_symbol}")

view raw JSON →