Guide · Open source

How to use Optuna: install, define an objective and run trials

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Optuna is a Python framework for hyperparameter optimization. It automatically tries different settings for a program or machine learning model and keeps the combination that scores best. This guide shows you how to install it, write an objective function, run a study and view the results in a web dashboard.

Optunaoptuna/optuna · ★ 15k · MIT Install options & downloads

Quick start

1Check your Python version. Optuna supports Python 3.10 or newer. Confirm your version before installing.
2Install Optuna. Run pip install optuna, or use conda install -c conda-forge optuna.
3Write an objective function. Define a function that takes a trial, calls suggest methods to get hyperparameters, and returns the score to minimize.
4Create a study. Call optuna.create_study() to make a new study, optionally with a storage URL to save results to a database.
5Run trials. Call study.optimize(objective, n_trials=100) to run the trials and find the best values.
6Open the dashboard (optional). Install optuna-dashboard with pip, then run optuna-dashboard with your storage URL and open the local address it prints.

What Optuna does and how it is organized

Optuna is designed for automating and speeding up optimization studies. You write an objective function that suggests values for hyperparameters and returns a score. Optuna then runs that function many times, and each run is called a trial.

A study is the optimization based on one objective function. Its goal is to find the set of hyperparameter values that gives the best result over many trials. Optuna uses a define-by-run API, so you can build the search space dynamically in ordinary Python code.

Study: optimization based on an objective function
Trial: a single execution of the objective function

Install Optuna with pip or conda

Optuna is available on the Python Package Index and on Anaconda Cloud. Optuna supports Python 3.10 or newer, so check your Python version first.

Install from PyPI with pip
Or install from Anaconda Cloud (conda-forge)

$ pip install optuna

Write an objective function and run a study

The objective function calls suggest methods on a trial object to generate hyperparameters, then returns a value to minimize. Create a study with optuna.create_study() and call study.optimize() with the number of trials you want.

The sample below tunes a choice between two regressors and their settings on the California housing dataset with scikit-learn. Its error value is the score that Optuna minimizes.

trial.suggest_categorical chooses between named options
trial.suggest_float and trial.suggest_int pick numeric values, with log=True for log-scale ranges
study.optimize(objective, n_trials=100) runs 100 trials

import optuna
import sklearn


# Define an objective function to be minimized.
def objective(trial):

    # Invoke suggest methods of a Trial object to generate hyperparameters.
    regressor_name = trial.suggest_categorical("regressor", ["SVR", "RandomForest"])
    if regressor_name == "SVR":
        svr_c = trial.suggest_float("svr_c", 1e-10, 1e10, log=True)
        regressor_obj = sklearn.svm.SVR(C=svr_c)
    else:
        rf_max_depth = trial.suggest_int("rf_max_depth", 2, 32)
        regressor_obj = sklearn.ensemble.RandomForestRegressor(max_depth=rf_max_depth)

    X, y = sklearn.datasets.fetch_california_housing(return_X_y=True)
    X_train, X_val, y_train, y_val = sklearn.model_selection.train_test_split(X, y, random_state=0)

    regressor_obj.fit(X_train, y_train)
    y_pred = regressor_obj.predict(X_val)

    error = sklearn.metrics.mean_squared_error(y_val, y_pred)

    return error  # An objective value linked with the Trial object.


study = optuna.create_study()  # Create a new study.
study.optimize(objective, n_trials=100)  # Invoke optimization of the objective function.

Save results to a database and view them in the dashboard

Passing a storage URL to create_study saves the study to a database, here a SQLite file. Optuna Dashboard is a real-time web dashboard that shows optimization history and hyperparameter importance in graphs and tables, without writing extra Python for the visualization functions.

Install the dashboard as an optional package, run your script, then launch the dashboard pointing at the same storage. It listens on localhost port 8080 in the example output.

Install the dashboard with pip install optuna-dashboard
Launch it with optuna-dashboard sqlite:///db.sqlite3, then open http://localhost:8080/

import optuna


def objective(trial):
    x1 = trial.suggest_float("x1", -100, 100)
    x2 = trial.suggest_float("x2", -100, 100)
    return x1**2 + 0.01 * x2**2


study = optuna.create_study(storage="sqlite:///db.sqlite3")  # Create a new study with database.
study.optimize(objective, n_trials=100)

Know the limits and the Rustuna alternative

Optuna is a Python API, so you need to write code to use it. The README only shows Python usage. If your objective function is very cheap and sampling speed is the bottleneck, the README points to Rustuna, a faster implementation of Optuna written in Rust. It is experimental, so the README warns that it still lacks some features and APIs and that bugs likely remain.

Optuna's key features include pythonic search spaces with conditionals and loops, pruning of unpromising trials, and easy parallelization across many workers with little or no code change.

Use Optuna for ML model tuning and general Python objective functions
Consider Rustuna only if you accept experimental software for speed
Comparable projects named in the analysis include Ray Tune, Hyperopt, scikit-optimize and Weights & Biases Sweeps

What people use it for

Tuning the learning rate or tree depth of a machine learning model
Automating trial-and-error on any Python objective function
Running the same search across multiple workers in parallel
Inspecting optimization history and parameter importance in a web dashboard

Frequently asked questions

Is Optuna free to use?

Yes. Optuna is released under the MIT licence, as stated in the project's README and licence badge.

What Python version do I need for Optuna?

Optuna supports Python 3.10 or newer. Check your version before you run pip install optuna.

How do I install Optuna?

Run pip install optuna from the Python Package Index, or run conda install -c conda-forge optuna on Anaconda Cloud.

How do I open the Optuna dashboard?

Install it with pip install optuna-dashboard, then run optuna-dashboard with your storage URL, such as sqlite:///db.sqlite3. Open the localhost address it prints, which the example shows as port 8080.

Does Optuna work without writing code?

No. The README describes a Python API that requires writing code, so Optuna is not a no-code tool.

What are alternatives to Optuna?

The analysis lists Ray Tune, Hyperopt, scikit-optimize and Weights & Biases Sweeps as comparable projects. For very cheap objective functions, the README points to the experimental Rustuna project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Optuna suits Python developers and machine learning practitioners who want to automate hyperparameter search with ordinary code and optionally inspect results in a dashboard. It is a poor fit if you need a no-code tool, a non-Python codebase, or the fastest possible sampling for very cheap objectives, where the README suggests trying the experimental Rustuna instead.

Install options & downloads