optuna_integration.TrackioCallback

class optuna_integration.TrackioCallback(project, metric_name='value', *, as_multirun=False, space_id=None, dataset_id=None, private=None, resume='allow', trackio_kwargs=None)

Callback to track Optuna trials with Trackio.

This callback enables tracking of an Optuna study using Trackio. By default, the entire study is recorded as a single experiment run, where all suggested hyperparameters and optimized metrics are logged and visualized as a function of optimizer steps.

Trackio is offline-first and does not require authentication for local usage. Optionally, results can be synchronized to Hugging Face Spaces or exported as Hugging Face Datasets for sharing, visualization, and reproducibility.

Note

Trackio does not require users to be logged in for local experiment tracking. Authentication is only required when synchronizing results to Hugging Face Hub (e.g., Spaces or Datasets).

Note

Unlike Weights & Biases, Trackio does not rely on global mutable state. Each run is explicitly initialized and finalized, which makes this callback safe to use in long-running processes and research pipelines.

Note

To ensure deterministic trial ordering in logged metrics, this callback should only be used with study.optimize(n_jobs=1). Parallel optimization may result in out-of-order steps.

Example

Add Trackio callback to Optuna optimization.

import optuna
from optuna_integration.trackio import TrackioCallback


def objective(trial):
    x = trial.suggest_float("x", -10, 10)
    return (x - 2) ** 2


study = optuna.create_study()

trackioc = TrackioCallback(project="my-optuna-study")

study.optimize(objective, n_trials=10, callbacks=[trackioc])

Trackio logging in multi-run (one run per trial) mode.

import optuna
from optuna_integration.trackio import TrackioCallback


trackioc = TrackioCallback(
    project="my-optuna-study",
    as_multirun=True,
)


# Required when logging per-trial runs
@trackioc.track_in_trackio()
def objective(trial):
    x = trial.suggest_float("x", -10, 10)
    return (x - 2) ** 2


study = optuna.create_study()
study.optimize(objective, n_trials=10, callbacks=[trackioc])

Publishing results to a Hugging Face Space.

trackioc = TrackioCallback(
    project="my-optuna-study",
    space_id="username/optuna-dashboard",
    as_multirun=True,
)

Parameters:

• project (str) – Name of the Trackio project. This determines the local storage directory and is also used when synchronizing results to a Hugging Face Space or Dataset.

• metric_name (str | Sequence[str]) –

  Name assigned to the optimized metric. In case of multi-objective optimization, a sequence of names can be provided. These names are assigned to objective values in the order returned by the objective function.

  If a single name is provided (default: "value"), it will be broadcast to multiple objectives using a numerical suffix, e.g., value_0, value_1.

  The number of metric names must match the number of objective values returned.

• as_multirun (bool) –

  If True, creates a new Trackio run for each Optuna trial. This is useful for per-trial analysis, parameter importance visualizations, and sweep-style dashboards.

  If False (default), all trials are logged into a single run.

• space_id (str | None) – Optional Hugging Face Space ID ("username/space-name") to which the tracked project will be synchronized. If the Space does not exist, it will be created automatically.

• dataset_id (str | None) – Optional Hugging Face Dataset ID ("username/dataset-name") used to export trial metrics and parameters as a versioned dataset for offline analysis and reproducibility.

• private (bool | None) – Whether the Hugging Face Space or Dataset should be private. Defaults to the user or organization’s Hub settings.

• resume (str) – Resume behavior when initializing Trackio runs. This is particularly relevant for Optuna studies that may be restarted or retried. Accepted values are "allow", "must", and "never". The default "allow" enables safe resumption of existing runs while avoiding run name collisions.

• trackio_kwargs (dict[str, Any] | None) – Additional keyword arguments passed to trackio.init(), such as resume or UI-related configuration options.

Warning

Deprecated in v4.9.0. This feature will be removed in the future. The removal of this feature is currently scheduled for v6.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v4.9.0.

Methods

track_in_trackio()

Decorator for enabling Trackio logging inside the objective function.

track_in_trackio()

Decorator for enabling Trackio logging inside the objective function.

This decorator wraps an Optuna objective function so that a Trackio run is initialized before the objective executes and finalized afterward. Any calls to trackio.log() inside the objective will be associated with the correct run.

The decorator is required when logging from inside the objective function, since Optuna callbacks are invoked after a trial finishes and therefore cannot manage per-trial runtime state.

When as_multirun=True, a separate Trackio run is created for each Optuna trial. When as_multirun=False, all trials are logged into a single run.

Example

Add additional logging inside the objective function.

import optuna
import trackio
from optuna_integration.trackio import TrackioCallback

trackioc = TrackioCallback(
    project="my-optuna-study",
    as_multirun=True,
)


@trackioc.track_in_trackio()
def objective(trial: optuna.trial.Trial) -> float:
    x = trial.suggest_float("x", -10, 10)

    # Log custom metrics inside the objective
    trackio.log({"x": x, "loss_squared": (x - 2) ** 2})

    return (x - 2) ** 2


study = optuna.create_study()
study.optimize(objective, n_trials=10, callbacks=[trackioc])

Returns:

A wrapped objective function with Trackio logging enabled.

Return type:

Callable