Install & Compatibility
Where this runs
tested against v0.3.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 3.050s · 249MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.7s · import 2.866s · 240MB
252MB installed
● package 252MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fmin
✓ from hyperopt import fmin
✗ from hyperopt import fmin
This quickstart demonstrates how to use Hyperopt to find the minimum of a simple mathematical function. It involves defining an objective function, specifying a search space using `hp` functions, creating a `Trials` object to log results, and finally calling `fmin` with a chosen algorithm (TPE in this case) and the maximum number of evaluations.
import numpy as np
from hyperopt import fmin, tpe, hp, STATUS_OK, Trials
# 1. Define the objective function to minimize
def objective(args):
x, y = args
return {'loss': x ** 2 + y ** 2, 'status': STATUS_OK}
# 2. Define the search space
space = [
hp.uniform('x', -10, 10),
hp.uniform('y', -10, 10)
]
# 3. Create a Trials object to store results
trials = Trials()
# 4. Run the optimization
best = fmin(objective, space, algo=tpe.suggest, max_evals=100, trials=trials)
print("Best parameters found:", best)
print("Best loss found:", trials.best_trial['result']['loss'])
Debug
Known issues
breakingThe open-source version of Hyperopt is no longer being actively maintained. Databricks, a notable user, explicitly states this and recommends alternatives like Optuna for single-node optimization or Ray Tune for distributed tuning.fixFor new projects, consider using actively maintained hyperparameter optimization libraries such as Optuna or Ray Tune. If bound to Hyperopt, be aware that community support and bug fixes may be limited.
affects: 0.2.7 and potentially earlier/later versions
gotchaWhen using `hp.choice()` for categorical parameters, Hyperopt stores and returns the *index* of the chosen option from the list, not the actual value.fixTo retrieve the actual parameter value, use `hyperopt.space_eval(space, best_parameters)` where `space` is your defined search space and `best_parameters` are the results from `fmin`.
affects: All versions
gotchaA reported loss of NaN (not a number) often indicates that the objective function passed to `fmin()` returned `NaN`. This can lead to unexpected optimization behavior.fixReview your objective function to ensure it handles all possible input combinations from the search space gracefully and avoids returning NaN values. You might need to adjust the hyperparameter space to prevent problematic inputs.
affects: All versions
gotchaWhen using `SparkTrials` for distributed hyperparameter tuning, Hyperopt determines parallelism at the start. It will *not* dynamically adapt to changes in cluster size if the cluster autoscales.fixAvoid using `SparkTrials` on autoscaling clusters. For GPU clusters, be mindful that `SparkTrials` uses one executor thread per node, reducing maximum parallelism. `SparkTrials` is also primarily designed for single-machine ML models, not inherently distributed ones like MLlib or Horovod.
affects: All versions using SparkTrials
gotchaDue to its use of stochastic search algorithms, Hyperopt's reported loss does not necessarily decrease monotonically with each evaluation. This is expected behavior and does not indicate an issue.fixUnderstand that the optimization process is not a smooth descent. Focus on the overall trend towards a lower loss and the final 'best' result, rather than expecting a strictly decreasing loss at every step.
affects: All versions
Upgrade
Version history
0.3.0latest on PyPI · released Jul 24, 2026
Audit
Dependencies
numpyrequiredCore dependency for numerical operations, required by hyperopt's optimization algorithms.
scipyrequiredCore dependency for scientific computing, especially for statistical distributions and numerical routines.