A Lightweight Experiment Tracking Library from Hugging Face

TL;DR: Trackio is a brand new, open-source, and free experiment tracking Python library that gives a neighborhood dashboard and seamless integration with Hugging Face Spaces for straightforward sharing and collaboration. Since trackio is a drop-in alternative for wandb, you possibly can start with the syntax you already know!

Background

If you could have trained your individual machine learning model, you realize how vital it’s to have the ability to trace metrics, parameters, and hyperparameters during training and visualize them afterwards to higher understand your training run.

Most machine learning researchers use specific experiment tracking libraries to do that. Nevertheless, these libraries might be paid, require complex setup, or lack the pliability needed for rapid experimentation and sharing.

Why We Switched to Trackio

At Hugging Face, our science team has began using Trackio for our research projects, and we have found several key benefits over other tracking solutions:

Easy Sharing and Embedding: Trackio makes it incredibly easy to share training progress with colleagues or embed plots directly in blog posts and documentation using iframes. This is very invaluable when you must showcase specific training curves or metrics without requiring others to establish accounts or navigate complex dashboards.

Standardization and Transparency: Metrics like GPU energy usage are vital to trace and share with the community so we are able to have a greater idea of the energy demands and environmental impacts of model training. Using Trackio, which directly gets information from the nvidia-smi command, makes it easy to quantify and compare energy usage and so as to add it to model cards.

Data Accessibility: Unlike some tracking tools that lock your data behind proprietary APIs, Trackio makes it straightforward to extract and analyze the info being recorded. That is crucial for researchers who must perform custom evaluation or integrate training metrics into their research workflows.

Flexibility for Experimentation: Trackio’s lightweight design allows us to simply experiment with recent tracking features during training runs. As an example, we are able to determine when to maneuver tensors from GPU to CPU when logging tensors while training, which significantly improves training throughput when you have to track model/intermediate states without impacting performance.

Using Trackio

Okay then, so what’s Trackio and the way do you utilize it? Trackio is an open-source Python library that enables you to track any metrics and visualize them using a neighborhood Gradio dashboard. It’s also possible to sync this dashboard to Hugging Face Spaces, which implies you possibly can then share the dashboard with other users just by sharing a URL. Since Spaces might be private or public, this implies you possibly can share a dashboard publicly or simply inside members of your Hugging Face organization.

Installing

You’ll be able to install trackio using pip:

pip install trackio

Or, for those who prefer using uv:

uv pip install trackio

Usage

trackio is designed to be a drop-in alternative for experiment tracking libraries like wandb. The API is compatible with wandb.init, wandb.log, and wandb.finish, so you possibly can simply import trackio as wandb in your code.

- import wandb
+ import trackio as wandb

Here is an example:

import trackio
import random
import time

runs = 3
epochs = 8

def simulate_multiple_runs():
    for run in range(runs):
        trackio.init(project="fake-training", config={
            "epochs": epochs,
            "learning_rate": 0.001,
            "batch_size": 64
        })
        for epoch in range(epochs):
            train_loss = random.uniform(0.2, 1.0)
            train_acc = random.uniform(0.6, 0.95)
            val_loss = train_loss - random.uniform(0.01, 0.1)
            val_acc = train_acc + random.uniform(0.01, 0.05)
            trackio.log({
                "epoch": epoch,
                "train_loss": train_loss,
                "train_accuracy": train_acc,
                "val_loss": val_loss,
                "val_accuracy": val_acc
            })
            time.sleep(0.2)
        trackio.finish()

simulate_multiple_runs()

Visualizing Results

After logging your experiments, you possibly can launch the dashboard to visualise your results. Run the next command in your terminal:

trackio show

Or, launch it from Python:

import trackio
trackio.show()

It’s also possible to specify a project name:

trackio show --project "my project"

Or in Python:

trackio.show(project="my project")

Sharing with 🤗 Spaces

To sync your local dashboard to Hugging Face Spaces, simply pass a space_id to init:

trackio.init(project="fake-training", space_id="org_name/space_name")

In case you are hosting your dashboard on Spaces, you possibly can simply share the URL or embed it anywhere using an iframe:

<iframe src="https://org_name-space_name.hf.space/?project=fake-training&metrics=train_loss,train_accuracy&sidebar=hidden" width=600 height=600 frameBorder="0">iframe>

Since Spaces might be private or public, this implies you possibly can share a dashboard publicly or simply inside members of your Hugging Face organization — all without cost!

While you sync your Trackio dashboard to Hugging Face Spaces, the info is logged to an ephemeral Sqlite database on Spaces. Because this database is reset in case your Space restarts, Trackio also converts the Sqlite database to a Parquet dataset and backs it as much as a Hugging Face Dataset every 5 minutes. This implies you possibly can visualize your logged metrics in a Hugging Face dataset at any time easily:

Tip: you possibly can set the name of this dataset by passing in a dataset_id to trackio.init().

Integrated with 🤗 Transformers and 🤗 Speed up

Trackio integrates natively with Hugging Face libraries like transformers and speed up, so you possibly can log metrics with minimal setup.

With transformers.Trainer:

import numpy as np
from datasets import Dataset
from transformers import Trainer, AutoModelForCausalLM, TrainingArguments


data = np.random.randint(0, 1000, (8192, 64)).tolist()
dataset = Dataset.from_dict({"input_ids": data, "labels": data})


trainer = Trainer(
    model=AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B"),
    args=TrainingArguments(run_name="fake-training", report_to="trackio"),
    train_dataset=dataset,
)
trainer.train()

With speed up:

from speed up import Accelerator

accelerator = Accelerator(log_with="trackio")
accelerator.init_trackers("fake-training")

...  

for step, batch in enumerate(dataloader):
    ...  
    accelerator.log({"training_loss": loss}, step=step)

accelerator.end_training()

No extra setup needed—just plug it in and begin tracking.

Design Principles

• API compatible with popular experiment tracking libraries, making migration each to and from Trackio seamless.
• Local-first: logs and dashboards run and persist locally by default, with the choice to host on Hugging Face Spaces.
• Lightweight and extensible: the core codebase is under 1,000 lines of Python, making it easy to grasp and modify.
• Free and open-source: all features, including hosting on Hugging Face, are free.
• Built on top of 🤗 Datasets and Spaces for robust data handling and visualization.

Next Steps

Trackio is intentionally lightweight and is currently in beta. Some features present in other tracking tools, similar to artifact management, or complex visualizations, should not available yet. In case you’d wish to have these features, please create issues here: https://github.com/gradio-app/trackio/issues

Given Trackio’s lightweight and open-source nature, we would like to work with the machine learning community to design an experiment tracking product that works for all of us!