Registry / data / currencyconverter

currencyconverter

library0.18.21pypypi✓ verified 23d ago

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.

data serialization

pip install currencyconverter

github ↗package ↗

INSTALL

IMPORT

SIG · CURRENCYCONVERTER

currencyconverter

datapythonv0.18.21

Install

1.6s avg

Import

100ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.18.21 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.104s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.096s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CurrencyConverter

✓ from currency_converter import CurrencyConverter

ECB_URL

✓ from currency_converter import ECB_URL

Used to fetch the latest historical data from ECB.

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.

from currency_converter import CurrencyConverter, ECB_URL from datetime import date import os # Initialize converter with the latest historical data from ECB (requires internet connection) # This downloads the full history, which can take a moment. # If you prefer to use the embedded data (might be outdated), use `c = CurrencyConverter()` c = CurrencyConverter(ECB_URL) # Convert 100 USD to EUR using the latest available rate amount_eur = c.convert(100, 'USD', 'EUR') print(f"100 USD = {amount_eur:.2f} EUR (latest historical rate)") # Convert 50 EUR to GBP on a specific date specific_date = date(2020, 1, 15) amount_gbp = c.convert(50, 'EUR', 'GBP', date=specific_date) print(f"50 EUR on {specific_date} = {amount_gbp:.2f} GBP") # List available currencies (e.g., to check supported codes) # print(c.currencies)

Debug

Known issues

gotchaThe 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.

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.

affects: All versions

gotchaThe 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.

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.

affects: All versions

gotchaA `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.

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'`).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'currency_converter'

This error occurs when the 'currencyconverter' library is not installed, or is installed but imported with the incorrect name (e.g., using an underscore instead of no underscore).

fix

Ensure the library is installed correctly using `pip install currencyconverter` and imported as `from currency_converter import CurrencyConverter` (note the underscore in the import, despite the package name not having one).

ValueError: AAA is not a supported currency.

This error indicates that the three-letter currency code provided (e.g., 'AAA') is not recognized or supported by the `CurrencyConverter` instance's data sources.

fix

Verify that the currency code is a valid ISO 4217 three-letter code and is present in the list of available currencies (e.g., by checking `c.currencies` after initializing `CurrencyConverter`).

RateNotFoundError: 1986-02-02 not in USD bounds 1999-01-04/2016-04-29

This error occurs when a currency conversion is requested for a date that falls outside the historical data range available for the specified currency, and fallback options are not enabled.

fix

Provide a `date` within the available bounds for the currency (as indicated in the error message, or by checking `c.bounds`), or initialize the `CurrencyConverter` with `fallback_on_wrong_date=True` to use the closest available date.

Upgrade

Version history

0.18.21latest on PyPI · released Aug 4, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alexprengere/currencyconverter ↗

packagehttps://pypi.org/project/currencyconverter/ ↗