{"library":"optuna","title":"Optuna","description":"Optuna is an automatic hyperparameter optimization framework for machine learning, featuring an imperative, define-by-run style user API that allows for dynamic construction of search spaces. It supports Python 3.9 or newer. The current version is 4.8.0, and it maintains an active development and release cadence, with major versions often introducing significant improvements and deprecating older features after a few releases.","status":"active","version":"4.8.0","language":"en","source_language":"en","source_url":"https://github.com/optuna/optuna","tags":["hyperparameter-optimization","machine-learning","deep-learning","optimization","HPO","AI"],"install":[{"cmd":"pip install optuna","lang":"bash","label":"Install Optuna"}],"dependencies":[{"reason":"Commonly used for examples and integration with ML models.","package":"scikit-learn","optional":true},{"reason":"Provides a real-time web dashboard for visualizing optimization history and hyperparameter importance.","package":"optuna-dashboard","optional":true}],"imports":[{"symbol":"optuna","correct":"import optuna"},{"note":"While `from optuna.trial import Trial` works, `from optuna import Trial` is the more common and recommended import pattern for the core `Trial` object as of recent versions.","wrong":"from optuna.trial import Trial","symbol":"Trial","correct":"from optuna import Trial"}],"quickstart":{"code":"import optuna\nimport sklearn\nfrom sklearn.ensemble import RandomForestRegressor\nfrom sklearn.model_selection import train_test_split\nfrom sklearn.datasets import fetch_california_housing\nfrom sklearn.metrics import mean_squared_error\n\ndef objective(trial: optuna.Trial) -> float:\n    # Invoke suggest methods of a Trial object to generate hyperparameters.\n    regressor_name = trial.suggest_categorical('regressor', ['SVR', 'RandomForest'])\n\n    if regressor_name == 'SVR':\n        svr_c = trial.suggest_float('svr_c', 1e-10, 1e10, log=True)\n        regressor_obj = sklearn.svm.SVR(C=svr_c)\n    else:\n        rf_max_depth = trial.suggest_int('rf_max_depth', 2, 32)\n        regressor_obj = RandomForestRegressor(max_depth=rf_max_depth, random_state=0)\n\n    X, y = fetch_california_housing(return_X_y=True)\n    X_train, X_val, y_train, y_val = train_test_split(X, y, random_state=0)\n\n    regressor_obj.fit(X_train, y_train)\n    y_pred = regressor_obj.predict(X_val)\n    error = mean_squared_error(y_val, y_pred)\n    return error\n\nif __name__ == '__main__':\n    study = optuna.create_study(direction='minimize')  # Create a new study\n    study.optimize(objective, n_trials=100)  # Invoke optimization\n\n    print(f\"Best trial value: {study.best_value:.4f}\")\n    print(f\"Best params: {study.best_params}\")\n","lang":"python","description":"This quickstart defines an objective function that trains either an SVR or RandomForestRegressor, with hyperparameters sampled by Optuna's `Trial` object. It then creates a study to minimize the mean squared error over 100 trials, showcasing how Optuna dynamically builds search spaces and finds optimal hyperparameters."},"warnings":[{"fix":"Review the Optuna v4 Migration Guide. For multi-objective optimization, the functionality was integrated into the single-objective API in v2.4.0, so adapt your code to use the unified API.","message":"Optuna v4.x removed features deprecated in v2.x. This includes the `optuna.multi_objective` submodule and `MOTPESampler`. If migrating from older versions, consult the v4 migration guide for a complete list of removed APIs.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update import paths and argument signatures for `IntersectionSearchSpace` and `intersection_search_space` to reflect their new locations and API changes.","message":"The paths for `IntersectionSearchSpace` and `intersection_search_space` moved from `optuna.samplers` to `optuna.search_space`. Additionally, `intersection_search_space` now takes `trials` instead of `study` and the `ordered_dict` argument was removed as dictionaries are now ordered by default.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Python environment to Python 3.9 or newer.","message":"Python 3.8 support was dropped in Optuna v4.x.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Ensure all arguments for samplers are passed as keyword arguments and review sampler-specific documentation for changes in argument behavior or deprecations.","message":"For some samplers, such as `TPESampler`, certain arguments have been made keyword-only, and the behavior of `consider_prior` argument might have changed or been simplified.","severity":"gotcha","affected_versions":">=4.4.0"},{"fix":"When performing multi-objective optimization, be mindful of scheduler compatibility. Consider using samplers and pruners specifically designed or enhanced for multi-objective tasks (e.g., `GPSampler` with multi-objective support from v4.4).","message":"Sophisticated schedulers (e.g., `AsyncHyperBandScheduler`) may not work correctly with multi-objective optimization, as they typically expect a scalar score to compare fitness among trials.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}