Install & Compatibility
Where this runs
tested against v0.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.866s · 142.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.0s · import 0.834s · 138MB
144MB installed
● package 144MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run_server
✓ from optuna_dashboard import run_server
Used for programmatically launching the dashboard within a Python application, as an alternative to the CLI.
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)")
optuna-dashboard --version
Debug
Known issues
deprecatedThe functions `optuna_dashboard.set_objective_names()` and `optuna_dashboard.artifact.upload_artifact()` are deprecated.fixUse `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.
affects: <0.16.1
gotchaHuman-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.fixUpgrade Optuna to v3.2 or later to ensure proper functionality for human-in-the-loop features.
affects: <0.10.0 (Optuna Dashboard) in conjunction with Optuna <3.2
gotchaThe 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.fixRefer to the official tutorial for LLM integration to configure your `config.toml` file or environment variables (`OPENAI_API_KEY`, etc.) correctly.
affects: >=0.20.0
gotchaThe dashboard uses port 8080 by default. If this port is already in use, the dashboard will fail to start.fixSpecify a different port using the `--port` argument (e.g., `optuna-dashboard --port 8081 sqlite:///db.sqlite3`).
affects: All versions
gotchaAfter significant UI updates (e.g., v0.10.0), users might experience a blank study page in the browser due to outdated browser cache.fixClear your browser's cache for the dashboard's URL.
affects: >=0.10.0
Errors
Common errors & fixes
optuna-dashboard: command not found
The `optuna-dashboard` package is not installed or not in your system's PATH.
fixRun `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)
The default port (8080) that Optuna Dashboard tries to bind to is already occupied by another application.
fixLaunch 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.
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.
fixEnsure 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.
Browser caching issues, especially after a new version of the dashboard is released with UI changes.
fixClear your browser's cache and cookies for the dashboard's URL (`localhost:8080` or custom port), then refresh the page.
Upgrade
Version history
0.20.0latest on PyPI · released Nov 10, 2025
Audit
Dependencies
optunarequiredCore hyperparameter optimization framework that optuna-dashboard visualizes.
scikit-learnoptionalRequired for certain plots and examples in Optuna that rely on scikit-learn functionalities. It became an optional dependency in v0.20.0.