{"id":5052,"library":"scikit-optimize","title":"scikit-optimize (skopt)","description":"Scikit-Optimize, often referred to as skopt, is a simple and efficient Python library for sequential model-based optimization. It's designed to minimize expensive and noisy black-box functions, building on top of NumPy, SciPy, and Scikit-Learn. Version 0.10.2 is the current release. The library is under active development, with releases occurring periodically, making it a robust tool for tasks like hyperparameter tuning in machine learning.","status":"active","version":"0.10.2","language":"python","source_language":"en","source_url":"https://github.com/scikit-optimize/scikit-optimize","tags":["bayesian optimization","hyperparameter tuning","machine learning","optimization","scikit-learn"],"install":[{"cmd":"pip install scikit-optimize","lang":"bash","label":"Basic Installation"},{"cmd":"pip install scikit-optimize[plots]","lang":"bash","label":"Installation with Plotting Dependencies"},{"cmd":"conda install conda-forge::scikit-optimize","lang":"bash","label":"Conda Installation"}],"dependencies":[{"reason":"Core dependency for numerical operations.","package":"numpy","optional":false},{"reason":"Core dependency for scientific computing.","package":"scipy","optional":false},{"reason":"Core dependency, often used for hyperparameter tuning tasks.","package":"scikit-learn","optional":false},{"reason":"Optional dependency for plotting optimization results.","package":"matplotlib","optional":true}],"imports":[{"symbol":"gp_minimize","correct":"from skopt import gp_minimize"},{"symbol":"forest_minimize","correct":"from skopt import forest_minimize"},{"note":"While 'skopt.optimizer' exists, the top-level import 'from skopt import Optimizer' is the commonly documented and simpler approach for direct use.","wrong":"from skopt.optimizer import Optimizer","symbol":"Optimizer","correct":"from skopt import Optimizer"},{"note":"BayesSearchCV is exposed directly at the top level of the skopt package for convenience, despite residing within a submodule.","wrong":"from skopt.searchcv import BayesSearchCV","symbol":"BayesSearchCV","correct":"from skopt import BayesSearchCV"}],"quickstart":{"code":"import numpy as np\nfrom skopt import gp_minimize\n\ndef f(x):\n    # An example objective function to minimize\n    # In a real scenario, this could be a machine learning model training and evaluation\n    return (np.sin(5 * x[0]) * (1 - np.tanh(x[0] ** 2)) * \n            np.random.randn() * 0.1 + (x[0] - 0.5)**2)\n\n# Define the search space: a single dimension from -2.0 to 2.0\nspace = [(-2.0, 2.0)]\n\n# Perform Bayesian optimization using Gaussian Processes\n# n_calls: total number of objective evaluations\n# n_random_starts: number of random points to sample before fitting the surrogate model\n# random_state: for reproducibility\nres = gp_minimize(f, space, n_calls=20, n_random_starts=5, random_state=123)\n\nprint(f\"Optimal value found: x*={res.x[0]:.4f}, f(x*)={res.fun:.4f}\")","lang":"python","description":"This quickstart demonstrates how to use `gp_minimize` to find the minimum of a noisy black-box function within a defined search space. It sets up a simple 1D objective function and then applies Gaussian Process-based Bayesian optimization. The `random_state` ensures reproducibility."},"warnings":[{"fix":"Always pin exact versions (`scikit-optimize==X.Y.Z`) in production environments and review changelogs carefully when upgrading, particularly for minor version bumps.","message":"Despite being actively developed, `scikit-optimize` has previously been described as 'experimental and under heavy development'. This can imply that API stability, especially between minor versions, might not be as rigid as more mature libraries, potentially leading to breaking changes.","severity":"gotcha","affected_versions":"<=0.10.1"},{"fix":"Pass an integer to the `random_state` parameter in all relevant functions and classes (e.g., `gp_minimize(..., random_state=42)`).","message":"Reproducibility of optimization runs depends on setting the `random_state` parameter consistently across all components that use randomness (e.g., `gp_minimize`, `Optimizer`, base estimators in `BayesSearchCV`). Failing to do so can lead to different results across runs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For simple, self-contained optimization, use `gp_minimize` or similar functions. For custom loops, parallel evaluations, or dynamic stopping conditions, use the `Optimizer` class with its `ask()` and `tell()` methods, understanding how to manage the state.","message":"The library offers two main interfaces: direct minimization functions (e.g., `gp_minimize`) for complete optimization loops, and the `Optimizer` class for an 'ask-and-tell' interface, providing more fine-grained control over the optimization process. Confusing these or misapplying the `ask-and-tell` pattern can lead to incorrect or inefficient optimization loops.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that your environment uses compatible versions of `numpy`, `scipy`, and `scikit-learn`. Refer to the `scikit-optimize` documentation or `setup.py` for recommended dependency versions. Using a fresh virtual environment or `conda-forge` for installation often helps manage these dependencies.","message":"As `scikit-optimize` is built on top of NumPy, SciPy, and Scikit-learn, version incompatibilities with these underlying libraries can occur. Outdated or incompatible versions of these dependencies might cause installation issues, runtime errors, or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.10.2':49 'activ':58 'base':24 'bayesian':77 'black':35 'black-box':34 'box':36 'build':38 'current':52 'design':28 'develop':59 'effici':17 'expens':31 'function':37 'hyperparamet':72,79 'learn':47,76,82,86 'librari':19,55 'like':71 'machin':75,81 'make':64 'minim':30 'model':23 'model-bas':22 'noisi':33 'numpi':42 'occur':62 'often':8 'optim':3,7,25,78,83 'period':63 'python':18 'refer':9 'releas':53,61 'robust':67 'scikit':2,6,46,85 'scikit-learn':45,84 'scikit-optim':1,5 'scipi':43 'sequenti':21 'simpl':15 'skopt':4,12 'task':70 'tool':68 'top':40 'tune':73,80 'version':48","created_at":"2026-04-12T16:52:00.599481+00:00","updated_at":"2026-04-16T21:25:22.457171+00:00","problems":[{"fix":"pip install scikit-optimize","cause":"The scikit-optimize library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'skopt'"},{"fix":"from skopt.space import Real, Integer, Categorical\n\ndef objective(params):\n    # ...\n    pass\n\ndimensions = [\n    Real(low=0.0, high=1.0, name='x1'),\n    Integer(low=1, high=10, name='x2')\n]\n\n# res = gp_minimize(objective, dimensions)","cause":"The classes for defining search space dimensions (Real, Integer, Categorical) were used without being imported from 'skopt.space'.","error":"NameError: name 'Real' is not defined"},{"fix":"def my_objective_function(params):\n    x = params[0]\n    y = params[1]\n    # Calculate a single scalar loss or metric\n    loss_value = (x - 0.5)**2 + (y + 0.2)**2\n    return loss_value  # Must return a single scalar","cause":"The objective function passed to scikit-optimize's optimizers (e.g., `gp_minimize`, `forest_minimize`) returned a non-scalar value (e.g., a list, tuple, or array) instead of a single float or integer.","error":"TypeError: objective function must return a scalar value."},{"fix":"from skopt import gp_minimize\nfrom skopt.plots import plot_convergence\nfrom skopt.space import Real\n\ndef objective_func(x): return x[0]**2\n\nres = gp_minimize(objective_func, [Real(-5.0, 5.0)], n_calls=10)\n\n# Correct: Pass a list containing the OptimizeResult object\nplot_convergence([res])\n\n# If comparing multiple results:\n# res2 = gp_minimize(objective_func, [Real(-5.0, 5.0)], n_calls=10, random_state=42)\n# plot_convergence([res, res2])","cause":"The `plot_convergence` function expects a list of `OptimizeResult` objects (or objects with a 'func_vals' attribute), but it was passed a raw NumPy array of objective function values.","error":"AttributeError: 'numpy.ndarray' object has no attribute 'func_vals'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://scikit-optimize.readthedocs.io/en/latest/contents.html","github":"https://github.com/holgern/scikit-optimize","docs":null,"changelog":null,"pypi":"https://pypi.org/project/scikit-optimize/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}