Optuna Hyperparameter Optimization Cheat Sheet
Define-by-run hyperparameter search with samplers, pruners, distributed studies, and integrations for PyTorch, LightGBM, and sklearn.
Define and Run a Study
Create an objective function and optimize it over a fixed number of trials.
import optunadef objective(trial): lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True) n_layers = trial.suggest_int("n_layers", 1, 4) optimizer_name = trial.suggest_categorical("optimizer", ["Adam", "SGD"]) dropout = trial.suggest_float("dropout", 0.0, 0.5, step=0.1) model = build_model(n_layers, dropout) accuracy = train_and_eval(model, lr, optimizer_name) return accuracy # value optuna will maximize/minimizestudy = optuna.create_study(direction="maximize", study_name="mnist-cnn")study.optimize(objective, n_trials=100, timeout=600)print(study.best_params)print(study.best_value)
Samplers and Pruners
Configure the search strategy and enable early stopping of unpromising trials.
from optuna.samplers import TPESamplerfrom optuna.pruners import MedianPrunerstudy = optuna.create_study( direction="minimize", sampler=TPESampler(seed=42), pruner=MedianPruner(n_startup_trials=5, n_warmup_steps=10),)def objective(trial): for epoch in range(30): loss = train_one_epoch() trial.report(loss, step=epoch) if trial.should_prune(): raise optuna.TrialPruned() return loss
Persistent and Distributed Studies
Store trials in a relational database so multiple workers can optimize the same study in parallel.
# create a persistent study backed by SQLite or PostgreSQLoptuna create-study --study-name "nlp-tuning" \ --storage "postgresql://user:pass@host/optuna_db"# each worker (on any machine) attaches to the same studypython train_worker.py # internally calls optuna.load_study(...)# inspect results from the CLIoptuna trials --study-name "nlp-tuning" --storage "postgresql://user:pass@host/optuna_db"
LightGBM Integration Example
Use suggested parameters directly inside a gradient boosting training loop.
import optunaimport lightgbm as lgbdef objective(trial): params = { "objective": "binary", "metric": "auc", "num_leaves": trial.suggest_int("num_leaves", 16, 256), "learning_rate": trial.suggest_float("learning_rate", 1e-3, 0.3, log=True), "feature_fraction": trial.suggest_float("feature_fraction", 0.5, 1.0), "bagging_fraction": trial.suggest_float("bagging_fraction", 0.5, 1.0), } gbm = lgb.train(params, train_set, valid_sets=[valid_set], callbacks=[lgb.early_stopping(50)]) preds = gbm.predict(X_valid) return roc_auc_score(y_valid, preds)study = optuna.create_study(direction="maximize")study.optimize(objective, n_trials=50)
Trial Suggestion API
The core methods used to define a search space inside an objective function.
- trial.suggest_float(name, low, high, log=False)- samples a continuous value, optionally on a log scale
- trial.suggest_int(name, low, high, step=1)- samples an integer, optionally stepped
- trial.suggest_categorical(name, choices)- samples from a fixed list of discrete options
- trial.report(value, step)- reports an intermediate value for pruning decisions
- trial.should_prune()- returns True if the current trial should be stopped early
- optuna.visualization.plot_optimization_history(study)- plots best-value progression across trials
Use trial.suggest_float with log=True for learning rates and regularization strengths — sampling uniformly on a linear scale wastes most trials in a range that barely affects the result.
Explore Topics
Professional Web Designing Services
- Responsive Websites
- E-commerce Solutions
- SEO Friendly Design
- Fast & Secure
- Support & Maintenance