Uncertainties: Error Propagation Library

3.2.4 · active · verified Sat Apr 11

The `uncertainties` package is an open-source Python library for doing calculations on numbers that have uncertainties (like 3.14±0.01). It automatically propagates uncertainties and handles correlations using linear error propagation theory. Maintained by the lmfit organization, it is actively developed, with version 3.2.4 released in January 2026, and a major 4.0.0 release is forthcoming.

Warnings

breaking Version 4.0.0 is under development and will introduce significant breaking changes, notably making `UFloat` objects immutable. Plan for migration once 4.0 is released.
Fix: Review the 4.0.0 release notes and documentation upon release for specific migration instructions.
breaking The handling of `numpy` as an optional dependency changed in version 3.2.3. Previously, importing a `numpy`-dependent function without `numpy` installed would raise an `ImportError`. Now, such functions can be imported, but attempting to execute them will raise a `NotImplementedError`.
Fix: Ensure `numpy` is installed (`pip install numpy`) if you intend to use `uncertainties.unumpy` or other `numpy`-dependent features.
deprecated `uncertainties.unumpy.umatrix` is deprecated as of version 3.2.2 and will be removed in version 4.0. This aligns with the broader discouragement of `numpy.matrix` in NumPy itself.
Fix: Replace usage of `unumpy.umatrix` with `unumpy.uarray` and standard NumPy array operations on `ufloat` objects, which are well-supported.
deprecated Several functions in `uncertainties.umath` (e.g., `ceil`, `fabs`, `floor`, `trunc`) and methods on `AffineScalarFunc`/`UFloat` objects (e.g., `__floordiv__`, `__mod__`, `__abs__`) were deprecated in 3.2.2 and will be removed in a future release.
Fix: Consult the `uncertainties` documentation for alternatives or use standard Python operations where applicable.
gotcha As of version 3.2.4, the stacklevel of the warning for `std_dev==0` has been increased. This means the warning will now point to the user's calling code rather than `ufloat()`, making it easier to diagnose the source of zero standard deviation inputs.
Fix: Review code for instances where `ufloat` is initialized with a standard deviation of zero if unexpected warnings appear.

Install

pip install uncertainties Install stable version

Imports

ufloat
```
from uncertainties import ufloat
```
umath
```
from uncertainties.umath import sin, cos
```
Provides mathematical functions for `ufloat` objects. Some functions are deprecated as of 3.2.2.
unumpy
```
from uncertainties import unumpy
```
Provides NumPy-like array and matrix operations for `ufloat` objects. `unumpy.umatrix` is deprecated.

Quickstart

Create numbers with uncertainties using `ufloat` and perform standard arithmetic or mathematical operations, with uncertainties automatically propagated.

from uncertainties import ufloat
from uncertainties.umath import sin

x = ufloat(2, 0.1)  # x = 2 +/- 0.1
y = ufloat(3, 0.2)  # y = 3 +/- 0.2

result_sum = x + y
result_product = x * y
result_sin = sin(x)

print(f"Sum: {result_sum}")
print(f"Product: {result_product}")
print(f"Sin(x): {result_sin}")

# Accessing nominal value and standard deviation
print(f"Nominal value of sum: {result_sum.nominal_value}")
print(f"Standard deviation of sum: {result_sum.std_dev}")

view raw JSON →