{"id":2139,"library":"numpy-financial","title":"NumPy Financial","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/numpy/numpy-financial","tags":["finance","numpy","financial analysis","scientific computing","economics"],"install":[{"cmd":"pip install numpy-financial","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency; provides the array object and underlying numerical operations. Requires NumPy version 1.15 or later.","package":"numpy","optional":false}],"imports":[{"note":"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`.","wrong":"import numpy as np; np.fv()","symbol":"npf","correct":"import numpy_financial as npf"},{"note":"Importing financial functions directly from `numpy` is no longer supported in NumPy versions 1.20 and above.","wrong":"from numpy import fv","symbol":"fv","correct":"from numpy_financial import fv"}],"quickstart":{"code":"import numpy_financial as npf\n\n# Calculate the present value (pv) of an annuity\n# A loan of 200,000, paid back over 30 years with monthly payments\n# at an annual interest rate of 5%.\n\nrate = 0.05 / 12     # Monthly interest rate (annual rate / 12)\nnper = 30 * 12       # Total number of payments (30 years * 12 months)\npmt = -1073.64       # Monthly payment (negative as it's an outflow)\nfv = 0               # Future value (loan is fully paid off)\nwhen = 'end'         # Payments at the end of each period\n\npresent_value = npf.pv(rate, nper, pmt, fv, when)\n\nprint(f\"The present value of the annuity is: ${present_value:,.2f}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"NumPy >= 1.20"},{"fix":"Update imports to use `numpy_financial` instead of `numpy` for financial functions (e.g., `import numpy_financial as npf` and use `npf.fv`).","message":"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`.","severity":"deprecated","affected_versions":"NumPy 1.18, 1.19"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}