optuna-dashboard: watching a hyperparameter search while it runs

A view onto a study, not the optimizer itself

optuna-dashboard is described as a real-time dashboard for Optuna, and the README says the code files were originally taken from Goptuna. That lineage explains the shape of the project, because Goptuna is a dashboard for a different hyperparameter optimization framework, and the code was reworked onto Optuna's storage model rather than written from scratch.

The important thing to understand is what the dashboard is not. It does not run trials. It does not schedule them, sample parameters or decide when to stop. Optuna does all of that, in your process, and the dashboard is a reader.

That distinction is the whole design. The dashboard connects to the same storage that Optuna writes to, which means it can show a study that is being optimized by a completely separate process, on a different machine, at the same time. You can start a sweep, leave it running, and open a browser to watch the optimization history fill in. For a search that takes hours and involves pruning, that is the difference between staring at a log file and seeing the picture.

The connection mechanism is the RDB backend. The README instructs you to specify the storage URL to persist your study using the RDB backend, and the dashboard is then pointed at the same URL. Optuna's own documentation on the RDB backend is linked for the details, and the storage is a SQL database, SQLite in the simplest case.

The audience is researchers and engineers who run Optuna as a library inside a larger training or tuning pipeline. This is not a hosted service and it does not manage studies for you; it renders the ones your code already created.

The three step loop, and the storage URL that anchors it

The README's getting started is three steps, and they are worth following exactly because the middle one is where people go wrong.

First, install it:

$ pip install optuna-dashboard

Second, run a study that persists to storage rather than keeping it in memory. The example creates a study with a storage URL and a study name, then optimizes it:

The example creates the study with optuna.create_study, passing storage="sqlite:///db.sqlite3" and study_name="quadratic-simple", and then calls study.optimize with n_trials=100 over an objective that suggests a float named x and a categorical named y.

The storage argument is the line that matters, and the inline comment in the example says to specify the storage URL here. Without it, the study lives only in the process that created it, and the dashboard has nothing to read.

Third, point the dashboard at the same URL:

$ optuna-dashboard sqlite:///db.sqlite3
Listening on http://localhost:8080/
Hit Ctrl-C to quit.

Two things to notice in that output. The server binds to localhost on port 8080, which is the right default for a tool that displays study internals. And the process runs in the foreground until you interrupt it, which is normal for a development server.

The study name in the example, quadratic-simple, matters more than it looks. A storage backend can hold many studies, and the dashboard shows them, so naming studies is how you keep a dashboard with twenty studies on it navigable.

The Docker image and its three supported databases

For anyone who does not want a Python environment, the project publishes an official Docker image, and the invocation is a single command:

$ docker run -it --rm -p 127.0.0.1:8080:8080 -v `pwd`:/app -w /app \
> ghcr.io/optuna/optuna-dashboard sqlite:///db.sqlite3

The volume mount and the working directory are what make this work. Mounting the current directory at /app and setting the working directory there means the sqlite:///db.sqlite3 URL resolves to the database file sitting in the directory you launched from, rather than to a path inside the container that vanishes when it exits.

The port mapping is bound to 127.0.0.1, so the dashboard is reachable only from the machine running it. That is a deliberate default and it is worth keeping, because a study database contains the hyperparameter space you searched, which is a map of what your model is sensitive to.

There is a hard limit on the database backends, stated in one line: the Docker image only supports SQLite3, MySQL with PyMySQL, and PostgreSQL with Psycopg2. The two connection string examples are given in full:

$ docker run -it --rm -p 127.0.0.1:8080:8080 ghcr.io/optuna/optuna-dashboard mysql+pymysql://username:password@hostname:3306/dbname

$ docker run -it --rm -p 127.0.0.1:8080:8080 ghcr.io/optuna/optuna-dashboard postgresql+psycopg2://username:password@hostname:5432/dbname

Note that the database host has to be reachable from inside the container, which is the usual Docker networking wrinkle. A SQLite file on the host works because of the volume mount; a Postgres server on the host needs a host address that resolves from within the container, not localhost.

Three experimental surfaces, three different trade-offs

The project is spreading out from the server application into three more places, and each is marked experimental in the README. The experiments are not variations on the same thing, they are different builds of the same idea with different capability.

The JupyterLab extension is the closest to the full dashboard. You install jupyterlab and jupyterlab-optuna from PyPI, click the tile to launch the extension, and enter your Optuna storage URL in the dialog. Since it runs inside the notebook environment, it shares the Python environment where your studies already live, which removes the storage URL copy-paste problem.

The browser-only version is the most interesting and the most restricted. It operates solely within your web browser and internally uses SQLite3 Wasm and Rust. There is no need to install Python or any other dependencies. You open a URL, drag and drop your SQLite3 file onto the page, and you are ready to view your Optuna studies.

The limitation is explicit: only a subset of features is available, though you can still check the optimization history, hyperparameter importances and similar in graphs and tables. So the browser build gives you the two views that matter most for a quick look, and drops the rest.

The VS Code extension follows the browser build, and the README says so directly. It is available from the Visual Studio Marketplace, with a code-server version on Open VSX, and you right-click a SQLite3 file in the explorer and choose Open in Optuna Dashboard. Because it is built on the browser-only version, the same limitations apply.

Taken together, the three give you a spectrum. The server application is the full one. The JupyterLab extension is nearly as full and lives inside your working environment. The browser and VS Code builds are for the case where you have a database file and nothing else, and the trade is explicitly a reduced feature set in exchange for zero installation.

How the code is put together across four languages

The repository layout explains the engineering effort behind a dashboard that looks like a web app.

There are four distinct trees. The optuna_dashboard directory holds the Python package with the server. The tslib directory holds shared TypeScript, split into types, storage and react subpackages, each built with its own filter. The rustlib directory contains a Rust crate compiled to WebAssembly, which is what the browser-only version runs on, and the Makefile has a target that produces optuna_wasm.js, optuna_wasm_bg.wasm and a package.json from it. The standalone_app and vscode directories hold the standalone browser build and the editor extension.

So the storage access is written twice, in two languages, for two very different environments. The server side is Python and talks to Optuna directly, since the package depends on optuna itself, 3.6.0 or newer, along with bottle for the web layer and tomli for Python versions below 3.11. The browser side cannot depend on Optuna, so it re-implements enough of the storage access in Rust compiled to WebAssembly, with SQLite3 Wasm underneath it.

The Docker build shows the full assembly. A node:22 stage runs pnpm install with a frozen lockfile and builds the TypeScript packages in order, types, storage, react, then the dashboard bundle, with the production build given a four gigabyte heap. A python:3.12-bookworm stage installs the Python package plus PyMySQL with rsa, psycopg2-binary and gunicorn, and copies the built frontend assets in from the first stage. A final python:3.12-slim-bookworm stage carries the result.

That build order is a good sanity check on the architecture. The React components are shared between the server dashboard and the standalone app, the storage abstraction is shared between them too, and only the storage implementation differs.

One detail in the Python configuration is worth knowing about if you hit a dependency conflict. The optional dependencies include a preferential group with torch and botorch, and the tool.uv section excludes packages newer than five days, with explicit exceptions for torch, optuna, rustuna and optuna-integration. This is a project that cares about not silently pulling a nightly into a reproducible environment.

What the dashboard cannot show, and the maintenance picture

The limits come from being a reader rather than the optimizer, and from the experimental surfaces.

The most obvious one is that the dashboard shows what has been persisted. If a study was created without a storage URL, there is nothing to display, and the dashboard will not be able to reconstruct a finished in-memory study. Studies that live only in memory are outside the model entirely.

The second is the browser build's feature subset, which the README states rather than hides, and which the VS Code extension inherits. If you need the full set of views, the server application is the one to run.

The third is the version coupling. The dashboard depends on Optuna 3.6.0 or newer, so an older Optuna in your environment is a problem, and the dashboard is classified as Development Status :: 3 - Alpha, which is a fair signal about how much the API may still move.

The fourth is that a dashboard is a local tool. It binds to loopback, it has no authentication in the documentation, and it displays a database containing your search history. Running it on a shared host without a reverse proxy in front of it is a decision you should make deliberately rather than by copying a command line.

On maintenance, the picture is good. The repository is not archived, the last push was on 2026-10-15, and the releases are v0.21.0 from 2026-09-10, jupyterlab-v0.3.0 from 2026-06-17 and v0.20.0 from 2025-11-10. The fact that the JupyterLab extension has its own release line, separate from the main one, confirms that the experimental surfaces are versioned independently rather than bundled into the main package.

The licence is MIT, declared both in the pyproject.toml as MIT License and in the README badge, and the repository carries the LICENSE file. The package description is Real-time dashboard for Optuna, and the author is Masashi Shibata.

Editorial conclusion

Adopt optuna-dashboard if you run Optuna with a persistent RDB storage backend and want to watch a search as it progresses, especially across a long hyperparameter sweep. Do not adopt it for a study kept only in memory, since the dashboard reads from storage, and prefer the full server build over the browser only version when you need the complete feature set. Verify first that your storage URL is reachable from wherever the dashboard runs, that the Optuna version in your environment satisfies the 3.6.0 floor, and that the process binding the dashboard port is not exposed beyond localhost.

Frequently asked questions

Official sources

1. Issues
2. optuna/optuna-dashboard on GitHub
3. Project website
4. README
5. Releases