{"id":2064,"library":"hyperopt","title":"Hyperopt","description":"Hyperopt is a Python library for distributed asynchronous hyperparameter optimization, enabling optimization over awkward search spaces including real-valued, discrete, and conditional dimensions. It uses Bayesian optimization algorithms like Tree of Parzen Estimators (TPE) and Random Search to efficiently find optimal hyperparameters for machine learning models. The current PyPI version is 0.2.7.","status":"deprecated","version":"0.2.7","language":"en","source_language":"en","source_url":"https://github.com/hyperopt/hyperopt","tags":["hyperparameter optimization","machine learning","bayesian optimization","distributed computing"],"install":[{"cmd":"pip install hyperopt","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Core dependency for numerical operations, required by hyperopt's optimization algorithms.","package":"numpy"},{"reason":"Core dependency for scientific computing, especially for statistical distributions and numerical routines.","package":"scipy"}],"imports":[{"note":"The main function to minimize an objective over a search space.","symbol":"fmin","correct":"from hyperopt import fmin"},{"note":"Module containing the Tree-structured Parzen Estimator (TPE) algorithm, a common choice for optimization.","symbol":"tpe","correct":"from hyperopt import tpe"},{"note":"Module for defining hyperparameter search spaces (e.g., hp.uniform, hp.choice).","symbol":"hp","correct":"from hyperopt import hp"},{"note":"Used to store the results of the optimization (hyperparameters, loss, etc.).","symbol":"Trials","correct":"from hyperopt import Trials"}],"quickstart":{"code":"import numpy as np\nfrom hyperopt import fmin, tpe, hp, STATUS_OK, Trials\n\n# 1. Define the objective function to minimize\ndef objective(args):\n    x, y = args\n    return {'loss': x ** 2 + y ** 2, 'status': STATUS_OK}\n\n# 2. Define the search space\nspace = [\n    hp.uniform('x', -10, 10),\n    hp.uniform('y', -10, 10)\n]\n\n# 3. Create a Trials object to store results\ntrials = Trials()\n\n# 4. Run the optimization\nbest = fmin(objective, space, algo=tpe.suggest, max_evals=100, trials=trials)\n\nprint(\"Best parameters found:\", best)\nprint(\"Best loss found:\", trials.best_trial['result']['loss'])","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"The 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.","severity":"breaking","affected_versions":"0.2.7 and potentially earlier/later versions"},{"fix":"To 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`.","message":"When using `hp.choice()` for categorical parameters, Hyperopt stores and returns the *index* of the chosen option from the list, not the actual value.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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.","message":"A 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions using SparkTrials"},{"fix":"Understand 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.","message":"Due 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.","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"}