Install & Compatibility
Where this runs
tested against v1.0.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.232s · 89.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.278s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
npf
✓ import numpy_financial as npf
✗ import numpy as np; np.fv()
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
✗ from numpy import fv
Importing financial functions directly from `numpy` is no longer supported in NumPy versions 1.20 and above.
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}")
Debug
Known issues
breakingThe 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.fixMigrate 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`.
affects: NumPy >= 1.20
deprecatedThe 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`.fixUpdate imports to use `numpy_financial` instead of `numpy` for financial functions (e.g., `import numpy_financial as npf` and use `npf.fv`).
affects: NumPy 1.18, 1.19
gotchaCalculations 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.fixBe 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.
affects: All versions
gotchaThe 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.fixPerform 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numpy_financial'
The 'numpy-financial' package is not installed in the Python environment where the code is being run.
fixInstall the package using pip: `pip install numpy-financial`.
AttributeError: module 'numpy' has no attribute 'pv'
Financial functions like 'pv', 'irr', and 'fv' were deprecated and removed from the main NumPy library; they now reside in the 'numpy-financial' package. The code is attempting to access these functions from the 'numpy' module instead of 'numpy_financial'.
fixImport 'numpy_financial' and call the function from its namespace, commonly aliased as 'npf': `import numpy_financial as npf` then use `npf.pv(...)`.
NameError: name 'npf' is not defined
The alias 'npf' for 'numpy_financial' was used without first executing the import statement `import numpy_financial as npf` or the import statement was not in the correct scope.
fixEnsure that `import numpy_financial as npf` is executed successfully before any calls to `npf.function()` are made.
Upgrade
Version history
1.0.0latest on PyPI · released Oct 18, 2019
Audit
Dependencies
numpyrequiredCore dependency; provides the array object and underlying numerical operations. Requires NumPy version 1.15 or later.