Install & Compatibility
Where this runs
tested against v0.10.1 · 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 1.234s · 231.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.3s · import 1.208s · 223MB
231MB installed
● package 231MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
numdifftools
✓ import numdifftools as nd
Derivative
✓ from numdifftools import Derivative
✗ import numdifftools.Derivative
Classes like Derivative, Gradient, etc., are typically accessed via the top-level 'nd' alias or imported directly, not as submodules.
This quickstart demonstrates how to compute the first and second derivatives of a scalar function, and the gradient of a multivariate function using `numdifftools.Derivative` and `numdifftools.Gradient`.
import numpy as np
import numdifftools as nd
def f(x):
return x**3 + x**2
# Compute the 1st derivative of f(x) at x=1
df = nd.Derivative(f)
result_df = df(1)
print(f"First derivative of f(x) at x=1: {result_df}")
# Compute the 2nd derivative of f(x) at x=1
ddf = nd.Derivative(f, n=2)
result_ddf = ddf(1)
print(f"Second derivative of f(x) at x=1: {result_ddf}")
# Compute the gradient of a multivariate function
def rosen(x):
return (1 - x[0])**2 + 100 * (x[1] - x[0]**2)**2
grad = nd.Gradient(rosen)
result_grad = grad([1, 1]) # At the minimum of Rosenbrock function
print(f"Gradient of Rosenbrock at (1,1): {result_grad}")
Debug
Known issues
gotchaThe complex-step differentiation method, while highly accurate and robust to round-off errors, requires the target function to be analytic and support complex number inputs. It will fail for non-analytic functions (e.g., `abs`, `max`, `min`) or functions that do not handle complex inputs gracefully.fixFor non-analytic functions or those that do not support complex inputs, use 'central' or other finite difference methods by setting the `method` parameter (e.g., `nd.Derivative(func, method='central')`).
affects: All versions
gotchaSelecting an inappropriate step size can lead to inaccurate results. Too small a step size may introduce round-off errors, while too large a step size can increase approximation errors. Numdifftools attempts to adaptively select an optimal step size, but manual override with `step` parameter should be done cautiously.fixRely on the library's adaptive step size selection when possible. If manually setting `step`, ensure it's within a reasonable range to balance approximation and round-off errors. Monitor error estimates provided by the tools.
affects: All versions
breakingIn versions around 0.9.15 to 0.9.18, a major API change occurred where the internal class member variable `self.f` was renamed to `self.fun`. If you were subclassing `numdifftools` classes or accessing these internal variables directly, your code would break.fixUpdate any custom code that directly accesses `self.f` to use `self.fun` instead. Always prefer using the public API where possible.
affects: 0.9.15 to 0.9.18 onwards
breakingIn version 0.9.41, there was an update where an import path from `scipy.ndimage.filters` was replaced by `scipy.ndimage`. Code relying on direct imports from the `filters` submodule of `scipy.ndimage` might encounter `ImportError`.fixIf encountering `ImportError` related to `scipy.ndimage.filters`, update import statements to use `scipy.ndimage` directly, or import the specific function from `scipy.ndimage` if it was moved.
affects: >=0.9.41
Errors
Common errors & fixes
Derivative(np.log, 1)(2.0)
Incorrect usage of the Derivative class; the order of the derivative should be specified using the 'n' parameter.
fixDerivative(np.log, n=1)(2.0)
ComplexWarning: Casting complex values to real discards the imaginary part
Using the 'complex' method for differentiation on functions that return real values can lead to complex results, causing this warning.
fixUse the 'central' method instead: nd.Hessian(function, method='central')
ModuleNotFoundError: No module named 'numdifftools'
The numdifftools package is not installed in the Python environment.
fixInstall the package using pip: pip install numdifftools
ModuleNotFoundError: No module named 'info'
This error typically indicates a corrupted or outdated numdifftools installation where an expected internal module, often related to `collections.namedtuple`, cannot be found.
fixUninstall the package and then reinstall it to ensure a clean and up-to-date installation: `pip uninstall numdifftools` followed by `pip install numdifftools`.
ValueError: setting an array element with a sequence
This commonly occurs when the function passed to numdifftools, particularly when leveraging algopy integration, expects a scalar or a specific array shape, but receives a sequence that it cannot correctly process into an array element.
fixEnsure that the function you are differentiating is designed to handle array-like inputs consistently. If using `numdifftools.nd_algopy`, review how `numpy.ndarray` types are handled within your function, as `algopy` has specific requirements for array objects.
Upgrade
Version history
0.10.1latest on PyPI · released Aug 12, 2026
Audit
Dependencies
numpyrequiredRequired for numerical operations and array handling.
scipyrequiredRequired for various scientific computing functionalities.
algopyoptionalOptional: Provides an easy-to-use interface to derivatives calculated with Algorithmic Differentiation (AD).
statsmodelsoptionalOptional: Extends functionality with some tools found in statsmodels.tools.numdiff.