Optuna Dashboard

0.20.0 · active · verified Thu Apr 16

Optuna Dashboard is a real-time web dashboard for Optuna, a popular hyperparameter optimization framework. It allows users to visualize and analyze hyperparameter optimization studies in real-time through interactive graphs and a rich trials data grid. The current version is 0.20.0, and it maintains a regular release cadence, with updates typically published more than 12 times a year.

Common errors

```
optuna-dashboard: command not found
```
cause The `optuna-dashboard` package is not installed or not in your system's PATH.

fix Run `pip install optuna-dashboard` to install the package. If it's already installed, ensure your Python environment's script directory is in your system's PATH.
```
Address already in use (os error 98)
```
cause The default port (8080) that Optuna Dashboard tries to bind to is already occupied by another application.

fix Launch the dashboard on a different port using `optuna-dashboard --port 8081 sqlite:///db/optuna_study.sqlite3` (or any other available port).
```
Error: SQLite database file 'db/optuna_study.sqlite3' does not exist.
```
cause The specified SQLite database file for the Optuna study does not exist or the path is incorrect. The dashboard cannot connect to a non-existent storage.

fix Ensure that your Optuna study has been run and saved to the specified `storage_url` before launching the dashboard. Verify the file path is correct.
```
Page goes blank or content disappears after loading study in browser.
```
cause Browser caching issues, especially after a new version of the dashboard is released with UI changes.

fix Clear your browser's cache and cookies for the dashboard's URL (`localhost:8080` or custom port), then refresh the page.

Warnings

deprecated The functions `optuna_dashboard.set_objective_names()` and `optuna_dashboard.artifact.upload_artifact()` are deprecated.
Fix: Use `study.set_metric_names()` and `optuna.artifacts.upload_artifact()` respectively. Note that the argument order for `upload_artifact()` is different in the new API. The `Boto3Backend` class is also deprecated; use `Boto3ArtifactStore` instead.
gotcha Human-in-the-loop optimization features (introduced with Optuna 3.2) may not work correctly with `_CachedStorage` in Optuna versions prior to v3.2 due to a bug preventing synchronization of trial information.
Fix: Upgrade Optuna to v3.2 or later to ensure proper functionality for human-in-the-loop features.
gotcha The LLM (Large Language Model) integration, supporting AI-assisted features like natural language querying and chart generation, requires specific configuration including API keys for providers like OpenAI or Azure OpenAI. These can be set via environment variables or a TOML configuration file.
Fix: Refer to the official tutorial for LLM integration to configure your `config.toml` file or environment variables (`OPENAI_API_KEY`, etc.) correctly.
gotcha The dashboard uses port 8080 by default. If this port is already in use, the dashboard will fail to start.
Fix: Specify a different port using the `--port` argument (e.g., `optuna-dashboard --port 8081 sqlite:///db.sqlite3`).
gotcha After significant UI updates (e.g., v0.10.0), users might experience a blank study page in the browser due to outdated browser cache.
Fix: Clear your browser's cache for the dashboard's URL.

Install

pip install optuna-dashboard PyPI
conda install -c conda-forge optuna-dashboard Conda

Imports

run_server
```
from optuna_dashboard import run_server
```
Used for programmatically launching the dashboard within a Python application, as an alternative to the CLI.

Quickstart

This quickstart runs an Optuna optimization study and persists its results to an SQLite database. You can then launch the Optuna Dashboard from your terminal, pointing to this database URL to visualize the study in real-time. The dashboard typically listens on `http://localhost:8080/`.

import optuna
import os

def objective(trial):
    x = trial.suggest_float("x", -100, 100)
    y = trial.suggest_categorical("y", [-1, 0, 1])
    return x**2 + y

if __name__ == "__main__":
    # Ensure the directory for the database exists
    os.makedirs("db", exist_ok=True)
    storage_url = "sqlite:///db/optuna_study.sqlite3"
    study = optuna.create_study(
        storage=storage_url,
        study_name="quadratic-simple",
        load_if_exists=True # Load existing study if it exists
    )
    print("Starting optimization...")
    study.optimize(objective, n_trials=10)
    print(f"Best value: {study.best_value} (params: {study.best_params})")
    print(f"Launch dashboard with: optuna-dashboard {storage_url}")
    print("Or via Python API (uncomment below):\n# from optuna_dashboard import run_server\n# run_server(storage_url)")

view raw JSON →