</div>

Welcome to trackio: a lightweight, <u>free</u> experiment tracking library built by Hugging Face 🤗. Trackio is local-first, supports very high logging throughputs for many parallel experiments, and provides an easy CLI interface for querying, perfect for LLM-driven experimenting.

For human users, Trackio ships with a Gradio-based dashboard so you can view metrics, media, tables, alerts, etc.:

Screen Recording 2025-11-06 at 5 34 50 PM

Trackio's main features:

API compatible with wandb.init, wandb.log, and wandb.finish. Drop-in replacement: just
```
import trackio as wandb
```
and keep your existing logging code.
Local-first design: dashboard runs locally by default. You can also host it on Spaces by specifying a space_id in trackio.init().
- Persists logs in a Sqlite database locally (or, if you provide a space_id, in a private Hugging Face Dataset)
- Visualize experiments with a Svelte 5 dashboard locally (or, if you provide a space_id, on Hugging Face Spaces)
LLM-friendly: Built with autonomous ML experiments in mind, Trackio includes a CLI for programmatic access and a Python API for run management, making it easy for LLMs to log metrics and query experiment data.
Free: Everything here, including hosting on Hugging Face, is free!

Trackio is designed to be lightweight and forkable: Python for the backend and API, Svelte 5 for the dashboard, and Gradio component code where UI widgets need to match Gradio behavior—so developers can fork the repository and extend either side.

Installation

Trackio requires Python 3.10 or higher. Install with pip:

pip install trackio

or with uv:

uv pip install trackio

Usage

To get started, you can run a simple example that logs some fake training metrics:

import trackio
import random
import time

runs = 3
epochs = 8


for run in range(runs):
    trackio.init(
        project="my-project",
        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()

Running the above will print to the terminal instructions on launching the dashboard.

The usage of trackio is designed to be identical to wandb in most cases, so you can easily switch between the two libraries.

import trackio as wandb

Dashboard

You can launch the dashboard by running in your terminal:

trackio show

or, in Python:

import trackio

trackio.show()

You can also provide an optional project name as the argument to load a specific project directly:

trackio show --project "my-project"

or, in Python:

import trackio 

trackio.show(project="my-project")

Deploying to Hugging Face Spaces

When calling trackio.init(), by default the service will run locally and store project data on the local machine.

But if you pass a space_id to init, like:

trackio.init(project="my-project", space_id="orgname/space_id")

trackio.init(project="my-project", space_id="username/space_id")

it will use an existing or automatically deploy a new Hugging Face Space as needed. You should be logged in with the huggingface-cli locally and your token should have write permissions to create the Space.

Syncing Offline Projects to Spaces

If you've been tracking experiments locally and want to move them to Hugging Face Spaces for sharing or collaboration, use the sync function:

import trackio

trackio.sync(project="my-project", space_id="username/space_id")

This uploads your local project database to a new or existing Space. The Space will display all your logged experiments and metrics.

Example workflow:

import trackio

# Start tracking locally
trackio.init(project="my-project", config={"lr": 0.001})
trackio.log({"loss": 0.5})
trackio.finish()

# Later, sync to Spaces
trackio.sync(project="my-project", space_id="username/my-experiments")

Embedding a Trackio Dashboard

One of the reasons we created trackio was to make it easy to embed live dashboards on websites, blog posts, or anywhere else you can embed a website.

If you are hosting your Trackio dashboard on Spaces, then you can embed the url of that Space as an IFrame. You can even use query parameters to only specific projects and/or metrics, e.g.

<iframe src="https://abidlabs-trackio-1234.hf.space/?project=my-project&metrics=train_loss,train_accuracy&sidebar=hidden" style="width:1600px; height:500px; border:0;">

Supported query parameters:

project: (string) Open the dashboard on this project only. The project picker is hidden and the selection cannot be changed while this parameter is present (useful for embeds). The alias selected_project is accepted for the same behavior.
metrics: (comma-separated list) Show only metrics whose names match exactly (after splitting on commas), e.g. train_loss,train_accuracy. Applied as the metrics filter on the Metrics page.
sidebar: (string) One of hidden, collapsed, or omitted (default). hidden removes the sidebar entirely (full-width content; no rail). collapsed starts with the sidebar collapsed to the narrow rail; the user can expand it. By default the sidebar is open.
footer: (string: "false"). When set to "false", hides the Gradio footer (Gradio-hosted Spaces). By default, the footer is visible.
xmin / xmax: (numbers, use both together) Set the initial horizontal zoom range on the Metrics plots (shared x-axis window). Both must be valid numbers with xmin < xmax.
smoothing: (number) Set the initial value of the smoothing slider (0-20, where 0 = no smoothing).
accordion: (string: "hidden"). When set to "hidden", hides the section header accordions around metric groups. By default, section headers are visible.
theme: (string) Dashboard theme, e.g. light or dark (see theme behavior in the app).
write_token: (string) One-time token written to a cookie for write access on Hugging Face Spaces deployments; stripped from the URL after load.

Alerts

Trackio supports alerts that let you flag important events during training. Alerts are printed to the terminal, stored in the database, displayed in the dashboard, and optionally sent to webhooks (Slack, Discord, or any URL).

import trackio

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    webhook_min_level=trackio.AlertLevel.WARN,
)

for epoch in range(100):
    loss = train(...)
    trackio.log({"loss": loss})

    if epoch > 10 and loss > 5.0:
        trackio.alert(
            title="Loss spike",
            text=f"Loss jumped to {loss:.2f} at epoch {epoch}",
            level=trackio.AlertLevel.ERROR,
        )

trackio.finish()

You can query alerts via the CLI (trackio get alerts --project "my-project" --json), the Python API (trackio.Api().alerts("my-project")), or the HTTP endpoint (/get_alerts). For full details, see the Alerts guide and the ML Agents guide.

Examples

To get started and see basic examples of usage, see these files:

Throughput & Rate Limits

Local logging

trackio.log() is a non-blocking call that appends to an in-memory queue and returns immediately. A background thread drains the queue every 0.5 s and writes to the local SQLite database. Because log calls never touch the network or disk on the calling thread, the client-side throughput is effectively unlimited -- you can burst thousands of calls per second without slowing down your training loop.

Logging to a Hugging Face Space

When a space_id is provided, the same background thread batches queued entries and pushes them to the Space via the Gradio client API. The main factors that affect end-to-end throughput are:

| Metric | Measured | Notes | |---|---|---| | Burst from a single run | 2,000 logs delivered in < 8 s | log() calls themselves complete in ~0.01 s; the rest is network drain time. |

Trackio

Install / Use

README