Install & Compatibility
Where this runs
tested against v2.32.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.396s · 94.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 0.404s · 87MB
93MB installed
● package 93MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Minuit
✓ from iminuit import Minuit
✗ import iminuit; minuit_obj = iminuit.Minuit(...)
The primary interface class is Minuit, typically imported directly.
UnbinnedNLL
✓ from iminuit.cost import UnbinnedNLL
✗ from iminuit import UnbinnedNLL
Built-in cost functions reside in the `iminuit.cost` submodule.
LeastSquares
✓ from iminuit.cost import LeastSquares
Another common built-in cost function.
This quickstart demonstrates a basic least-squares fit. It defines a model, creates a `LeastSquares` cost function, initializes `Minuit` with initial parameter guesses, runs `migrad()` for minimization, and then `hesse()` for error estimation. The results are printed and visualized.
import numpy as np
from iminuit import Minuit
from iminuit.cost import LeastSquares
from matplotlib import pyplot as plt
# 1. Generate some dummy data
np.random.seed(1)
x = np.linspace(0, 10, 50)
y_true = 2.5 * x + 1.2
y_err = 1.0 + x * 0.1
y_data = np.random.normal(y_true, y_err)
# 2. Define the model function
def model(x, a, b):
return a * x + b
# 3. Create a cost function using iminuit.cost.LeastSquares
# errordef=1 for least-squares fits
least_squares = LeastSquares(x, y_data, y_err, model)
# 4. Initialize Minuit with the cost function and initial parameter guesses
# Parameter names are auto-detected from the model function signature
m = Minuit(least_squares, a=0, b=0)
# 5. Run the minimization (MIGRAD algorithm)
m.migrad()
# 6. Run HESSE to compute accurate errors
m.hesse()
# 7. Print fit results and plot
print(m)
plt.errorbar(x, y_data, y_err, fmt='o', label='Data')
plt.plot(x, model(x, *m.values), label='Fit')
plt.xlabel('x')
plt.ylabel('y')
plt.legend()
plt.show()
Debug
Known issues
breakingVersion 2.x introduced significant breaking interface changes compared to 1.x. Older scripts are not directly compatible.fixReview the iminuit changelog for detailed migration guides and updated API usage. For legacy code, pin to 'iminuit<2'.
affects: 1.x -> 2.x
gotchaThe `errordef` parameter must be correctly set: `1.0` for least-squares (chi-squared) cost functions and `0.5` for negative log-likelihood functions. Incorrect `errordef` will lead to wrong error estimates.fixEnsure `errordef` is explicitly set or handled by the chosen `iminuit.cost` class. For `LeastSquares` use `errordef=1`, for `UnbinnedNLL` use `errordef=0.5`.
affects: All 2.x versions
gotchaThe Minuit `migrad` algorithm is a local minimizer. Providing poor initial parameter guesses can lead to convergence to local minima instead of the global minimum, or slow convergence.fixProvide reasonable starting values for parameters, ideally close to the expected minimum. Use multiple starting points if the function is complex with many local minima.
affects: All versions
gotchaAlways check the fit status (e.g., `m.valid`, `m.fmin.is_valid`) after calling `m.migrad()` or `m.hesse()`. `iminuit` can fail to converge or estimate errors accurately due to numerical issues, discontinuous cost functions, or reaching call limits.fixInspect `m.fmin` attributes (e.g., `edm`, `is_valid`) and `m.params` status. If `Accurate` is False for Hesse errors, call `m.hesse()` explicitly. Ensure cost functions are smooth and differentiable.
affects: All versions
gotchaMinuit (and thus iminuit) only supports independent box constraints on parameters (e.g., `a > 0`, `b < 5`). Complex, dependent parameter limits (e.g., `x^2 + y^2 < 1`) are not directly supported and require manual transformations or external minimizers.fixTransform variables to make limits independent, or use an external minimizer (like SciPy) for location finding, then use iminuit for error estimation with box constraints around the found minimum.
affects: All versions
Errors
Common errors & fixes
ImportError: No module named '_libiminuit'
This error often occurs when the `iminuit` Python package cannot find its underlying C++ MINUIT2 library, typically due to an incomplete or failed installation that requires a C++ compiler.
fixEnsure you have a C++ compiler installed (e.g., build-essential on Linux, Xcode command-line tools on macOS, Visual Studio build tools on Windows) and reinstall `iminuit` using `pip install --no-binary :all: iminuit` or `conda install iminuit`.
RuntimeError: starting value(s) are required for [...]
`iminuit` requires initial values for all parameters in the cost function to start the minimization process; if not provided, it cannot proceed.
fixProvide initial values for all parameters either as keyword arguments or as positional arguments when initializing the `Minuit` object. For example, `m = Minuit(my_cost_function, param1=1.0, param2=0.5)`.
InitialParamWarning: Parameter X does not have initial step size. Assume 1.
`iminuit` issues this warning when an initial step size (error) for a parameter is not explicitly provided, which can lead to slower convergence or suboptimal fitting behavior.
fixSet initial step sizes for parameters using the `error_` prefix in the constructor (e.g., `Minuit(fcn, a=1, error_a=0.1)`) or by assigning to `m.errors['param_name']` after initialization to guide the minimization process more effectively.
AttributeError: type object 'iminuit._libiminuit.Minuit' has no attribute 'from_array_func'
This `AttributeError` indicates that you are using a method or attribute (`from_array_func`) that was part of an older `iminuit` API (likely pre-2.x) and has since been removed or renamed in newer versions.
fixUpdate your code to use the modern `iminuit` 2.x API. Instead of `from_array_func`, pass functions that accept parameters as a NumPy array directly to the `Minuit` constructor, providing initial values as an array-like object. For example, `m = Minuit(fcn_np_array, [1.0, 0.5])`.
TypeError: migrad() got an unexpected keyword argument 'precision'
The `migrad` method in `iminuit` versions 2.x and later no longer accepts a `precision` keyword argument; this was an option in older versions of the library.
fixRemove the `precision` argument from your `m.migrad()` call. If you need to influence convergence, consider adjusting `Minuit.strategy` or `Minuit.tol` (tolerance).
Upgrade
Version history
2.32.0latest on PyPI · released Nov 9, 2025
Audit
Dependencies
numpyrequiredCore dependency for numerical operations.
numbaoptionalEnables partial JIT-compilation of cost functions for performance.
matplotliboptionalRequired for visualization of fitted models and interactive fitting with ipywidgets.
ipywidgetsoptionalEnables interactive fitting in Jupyter notebooks (requires matplotlib).
scipyoptionalUsed for computing Minos intervals for arbitrary confidence levels and alternative minimizers.
unicodeitplusoptionalRenders names of model parameters in simple LaTeX as Unicode.