{"id":4923,"library":"currencyconverter","title":"CurrencyConverter","description":"CurrencyConverter is a Python library that provides historical currency exchange rates, primarily using data from the European Central Bank (ECB). It allows conversion between various currencies based on specified dates or the latest available historical rate. The library is compatible with Python 3.9+ and is actively maintained, with the current version being 0.18.16.","status":"active","version":"0.18.16","language":"en","source_language":"en","source_url":"https://github.com/alexprengere/currencyconverter","tags":["currency","exchange rates","ECB","historical data","financial"],"install":[{"cmd":"pip install currencyconverter","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"symbol":"CurrencyConverter","correct":"from currency_converter import CurrencyConverter"},{"note":"Used to fetch the latest historical data from ECB.","symbol":"ECB_URL","correct":"from currency_converter import ECB_URL"}],"quickstart":{"code":"from currency_converter import CurrencyConverter, ECB_URL\nfrom datetime import date\nimport os\n\n# Initialize converter with the latest historical data from ECB (requires internet connection)\n# This downloads the full history, which can take a moment.\n# If you prefer to use the embedded data (might be outdated), use `c = CurrencyConverter()`\nc = CurrencyConverter(ECB_URL)\n\n# Convert 100 USD to EUR using the latest available rate\namount_eur = c.convert(100, 'USD', 'EUR')\nprint(f\"100 USD = {amount_eur:.2f} EUR (latest historical rate)\")\n\n# Convert 50 EUR to GBP on a specific date\nspecific_date = date(2020, 1, 15)\namount_gbp = c.convert(50, 'EUR', 'GBP', date=specific_date)\nprint(f\"50 EUR on {specific_date} = {amount_gbp:.2f} GBP\")\n\n# List available currencies (e.g., to check supported codes)\n# print(c.currencies)","lang":"python","description":"Initialize the `CurrencyConverter` object, optionally providing `ECB_URL` to download the latest historical rates. Then use the `convert()` method to perform conversions between an amount, source currency, target currency, and an optional specific date."},"warnings":[{"fix":"Always initialize with `CurrencyConverter(ECB_URL)` if you need recent historical rates. Be aware this requires an internet connection and will download the full historical dataset on initialization. Consider caching the downloaded file for performance in production environments.","message":"The default `CurrencyConverter()` constructor uses embedded historical data that is packaged with the library and might be significantly outdated. It does not query real-time APIs. For up-to-date historical rates, you must explicitly initialize it with `ECB_URL` (e.g., `CurrencyConverter(ECB_URL)`), which downloads the latest full historical data from the European Central Bank upon initialization.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you need to handle dates outside the ECB's historical range, initialize the converter with `fallback_on_wrong_date=True` (e.g., `CurrencyConverter(fallback_on_wrong_date=True)`). This will use the earliest or latest available rate for dates before or after the data's bounds, respectively. Also, be aware that while it converts between non-EUR currencies, these conversions are implicitly routed through EUR.","message":"The ECB data primarily provides rates against the Euro (EUR) and starts from January 1, 1999. Requesting conversions for dates before 1999 will raise a `RateNotFoundError` by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To enable fallbacks for missing rates on specific dates, initialize the converter with `fallback_on_missing_rate=True`. You can also configure the method of fallback (e.g., `fallback_on_missing_rate_method='last_known'` or `'linear_interpolation'`).","message":"A `RateNotFoundError` can occur if specific currency rates are missing for a requested date within the available data range. This is distinct from requesting dates outside the overall data bounds.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}