{"id":8386,"library":"optuna-dashboard","title":"Optuna Dashboard","description":"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.","status":"active","version":"0.20.0","language":"en","source_language":"en","source_url":"https://github.com/optuna/optuna-dashboard","tags":["machine-learning","hyperparameter-optimization","visualization","dashboard","optuna"],"install":[{"cmd":"pip install optuna-dashboard","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge optuna-dashboard","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core hyperparameter optimization framework that optuna-dashboard visualizes.","package":"optuna"},{"reason":"Required for certain plots and examples in Optuna that rely on scikit-learn functionalities. It became an optional dependency in v0.20.0.","package":"scikit-learn","optional":true}],"imports":[{"note":"Used for programmatically launching the dashboard within a Python application, as an alternative to the CLI.","symbol":"run_server","correct":"from optuna_dashboard import run_server"}],"quickstart":{"code":"import optuna\nimport os\n\ndef objective(trial):\n    x = trial.suggest_float(\"x\", -100, 100)\n    y = trial.suggest_categorical(\"y\", [-1, 0, 1])\n    return x**2 + y\n\nif __name__ == \"__main__\":\n    # Ensure the directory for the database exists\n    os.makedirs(\"db\", exist_ok=True)\n    storage_url = \"sqlite:///db/optuna_study.sqlite3\"\n    study = optuna.create_study(\n        storage=storage_url,\n        study_name=\"quadratic-simple\",\n        load_if_exists=True # Load existing study if it exists\n    )\n    print(\"Starting optimization...\")\n    study.optimize(objective, n_trials=10)\n    print(f\"Best value: {study.best_value} (params: {study.best_params})\")\n    print(f\"Launch dashboard with: optuna-dashboard {storage_url}\")\n    print(\"Or via Python API (uncomment below):\\n# from optuna_dashboard import run_server\\n# run_server(storage_url)\")","lang":"python","description":"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/`."},"warnings":[{"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.","message":"The functions `optuna_dashboard.set_objective_names()` and `optuna_dashboard.artifact.upload_artifact()` are deprecated.","severity":"deprecated","affected_versions":"<0.16.1"},{"fix":"Upgrade Optuna to v3.2 or later to ensure proper functionality for human-in-the-loop features.","message":"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.","severity":"gotcha","affected_versions":"<0.10.0 (Optuna Dashboard) in conjunction with Optuna <3.2"},{"fix":"Refer to the official tutorial for LLM integration to configure your `config.toml` file or environment variables (`OPENAI_API_KEY`, etc.) correctly.","message":"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.","severity":"gotcha","affected_versions":">=0.20.0"},{"fix":"Specify a different port using the `--port` argument (e.g., `optuna-dashboard --port 8081 sqlite:///db.sqlite3`).","message":"The dashboard uses port 8080 by default. If this port is already in use, the dashboard will fail to start.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Clear your browser's cache for the dashboard's URL.","message":"After significant UI updates (e.g., v0.10.0), users might experience a blank study page in the browser due to outdated browser cache.","severity":"gotcha","affected_versions":">=0.10.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `optuna-dashboard` package is not installed or not in your system's PATH.","error":"optuna-dashboard: command not found"},{"fix":"Launch the dashboard on a different port using `optuna-dashboard --port 8081 sqlite:///db/optuna_study.sqlite3` (or any other available port).","cause":"The default port (8080) that Optuna Dashboard tries to bind to is already occupied by another application.","error":"Address already in use (os error 98)"},{"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.","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.","error":"Error: SQLite database file 'db/optuna_study.sqlite3' does not exist."},{"fix":"Clear your browser's cache and cookies for the dashboard's URL (`localhost:8080` or custom port), then refresh the page.","cause":"Browser caching issues, especially after a new version of the dashboard is released with UI changes.","error":"Page goes blank or content disappears after loading study in browser."}]}