NumPy Financial

1.0.0 · active · verified Thu Apr 09

NumPy Financial is a Python library providing a collection of elementary financial functions. It serves as the standalone replacement for the financial functions that were deprecated and subsequently removed from the main NumPy library. Currently at version 1.0.0, the package aims for stability and maintains compatibility with NumPy, with releases typically occurring as needed for maintenance or feature parity.

Warnings

breaking The financial functions were completely removed from the main NumPy library in version 1.20. Any code relying on `numpy.fv`, `numpy.pmt`, etc., will fail with an `AttributeError` if NumPy 1.20 or newer is installed.
Fix: Migrate all calls to financial functions from `numpy` to `numpy_financial`. The function signatures remain the same, so typically only the import statement and object prefix (e.g., `np.fv` to `npf.fv`) need to be changed. Install `numpy-financial` via `pip install numpy-financial`.
deprecated The financial functions within NumPy itself were deprecated starting in NumPy version 1.18. Using them in NumPy 1.18 or 1.19 would issue `DeprecationWarning`s, advising users to switch to `numpy-financial`.
Fix: Update imports to use `numpy_financial` instead of `numpy` for financial functions (e.g., `import numpy_financial as npf` and use `npf.fv`).
gotcha Calculations involving a very large number of periods (`nper`), particularly for functions like `fv` (future value), can suffer from floating-point precision errors. This can lead to inaccurate or unexpected results, similar to limitations found in other financial software like Excel or Matlab.
Fix: Be aware of potential precision loss with extremely large `nper` values. For critical applications, consider external validation or explore alternative numerical methods if precision becomes an issue. This is a fundamental limitation of floating-point arithmetic rather than a bug in the library.
gotcha The functions in `numpy-financial` operate on generic periods (e.g., months, years) and do not natively handle actual dates or calendar considerations. Users must manage date-related complexities (like exact day counts or varying period lengths) externally.
Fix: Perform any date-specific calculations or adjustments (e.g., converting annual rates to effective monthly rates based on actual days, handling leap years) *before* passing the rate and period values to `numpy-financial` functions.

Install

pip install numpy-financial Install with pip

Imports

npf
```
import numpy_financial as npf
```
Financial functions were removed from NumPy 1.20. Using `np.` for financial functions will raise an AttributeError in newer NumPy versions. The recommended alias for numpy-financial is `npf`.
fv
```
from numpy_financial import fv
```
Importing financial functions directly from `numpy` is no longer supported in NumPy versions 1.20 and above.

Quickstart

This quickstart demonstrates how to calculate the present value (pv) of an annuity using common financial parameters. It shows the recommended import alias and a basic function call.

import numpy_financial as npf

# Calculate the present value (pv) of an annuity
# A loan of 200,000, paid back over 30 years with monthly payments
# at an annual interest rate of 5%.

rate = 0.05 / 12     # Monthly interest rate (annual rate / 12)
nper = 30 * 12       # Total number of payments (30 years * 12 months)
pmt = -1073.64       # Monthly payment (negative as it's an outflow)
fv = 0               # Future value (loan is fully paid off)
when = 'end'         # Payments at the end of each period

present_value = npf.pv(rate, nper, pmt, fv, when)

print(f"The present value of the annuity is: ${present_value:,.2f}")

view raw JSON →