# Trackio

> Source: https://aiwiki.ai/wiki/trackio
> Updated: 2026-10-25
> Fact-checked: 2026-10-25
> Categories: Developer Tools, MLOps, Machine Learning, Open Source AI
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "Trackio." aiwiki.ai, 25 Oct 2026. https://aiwiki.ai/wiki/trackio
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

**Trackio** is an open-source experiment tracking library for [Python](https://aiwiki.ai/wiki/python) developed by [Hugging Face](https://aiwiki.ai/wiki/hugging_face). It records metrics, configurations and media from machine learning training runs and displays them in a dashboard. The library is local-first: by default it stores data on the user's machine and runs the dashboard locally, with optional hosting on Hugging Face Spaces or a self-hosted server. Its logging API is modeled on that of [Weights & Biases](https://aiwiki.ai/wiki/wandb), and Hugging Face describes it as a drop-in replacement for the `wandb` package. The code is hosted in the `gradio-app/trackio` repository on GitHub under the [MIT License](https://aiwiki.ai/wiki/mit_license).[1][2]

Hugging Face announced Trackio in a blog post on July 29, 2025. As of October 25, 2026, the latest release on PyPI is version 0.43.0 (October 20, 2026), and the project's README still describes it as beta software whose database schema may change.[2][3][1]

## History

The GitHub repository was created on May 8, 2025, and the first package release on PyPI, version 0.0.2, was uploaded the same day. The earliest commits are by Abubakar Abid, who is also the repository's largest contributor by commit count. The PyPI metadata lists Abubakar Abid, Zach Nation and Saba Noorassa as authors.[4][3]

Version 0.1.0 was released on July 17, 2025. Integrations in Hugging Face's own training libraries arrived the same month: [Accelerate](https://github.com/huggingface/accelerate) 1.9.0 (July 16, 2025) added a Trackio tracker, and [Transformers](https://aiwiki.ai/wiki/transformers) 4.54.0 (July 25, 2025) added a Trackio integration contributed by Quentin Gallouédec.[3][5][6]

The announcement post, "Introducing Trackio: A Lightweight Experiment Tracking Library from Hugging Face", was written by Abubakar Abid, Zach Nation, Nouamane Tazi, Sasha Luccioni and Quentin Gallouédec. It said that Hugging Face's science team had started using Trackio for its research projects. The reasons it gave were easy sharing and embedding of plots, tracking of GPU energy usage read from `nvidia-smi` for inclusion in [model cards](https://aiwiki.ai/wiki/model_card), access to the raw logged data without proprietary APIs, and control over details such as when tensors are moved from GPU to CPU during logging.[2]

At launch the post described Trackio as "intentionally lightweight" and in beta, and said features found in other tracking tools, such as artifact management and complex visualizations, were not yet available. It gave the core codebase as under 1,000 lines of Python. InfoQ reported the release on September 2, 2025, repeating those limitations and noting reader questions about support for other Hugging Face tools such as Nanotron.[2][7] The current documentation describes the core codebase as under 3,000 lines of Python.[8]

An X account for the project, @TrackioApp, was created on August 27, 2025.[9]

### Release timeline

The project has shipped frequent minor releases. Selected changes from the project's changelog:[10][3]

| Version | Release date (PyPI) | Selected changes |
|---|---|---|
| 0.0.2 | May 8, 2025 | First PyPI release |
| 0.1.0 | July 17, 2025 | First 0.1 release |
| 0.6.0 | October 15, 2025 | Histogram support with a wandb-compatible API |
| 0.8.0 | November 5, 2025 | Trackio clients in Go, Rust and JavaScript |
| 0.9.0 | November 14, 2025 | Syncing offline projects to Hugging Face Spaces |
| 0.14.0 | January 5, 2026 | GPU metrics logging |
| 0.18.0 | March 4, 2026 | Alerts with webhooks; Apple Silicon GPU and system monitoring |
| 0.20.0 | March 25, 2026 | Dashboard uses Svelte source of Gradio components |
| 0.20.1 | March 27, 2026 | Static Trackio mode via `trackio.sync(sdk="static")` |
| 0.21.0 | April 8, 2026 | Hugging Face Buckets as backend; dataset backend deprecated |
| 0.24.0 | April 20, 2026 | `trackio query` SQL command; self-hosted server URLs; `gradio` dependency removed (only `gradio_client` needed locally) |
| 0.25.0 | April 23, 2026 | Traces; configurable custom frontends |
| 0.30.0 | July 8, 2026 | Artifact tracking API; experiment logbooks |
| 0.33.0 | July 24, 2026 | Persisting data to HF Datasets deprecated in favor of Buckets |
| 0.35.0 | August 13, 2026 | Artifact registry, lineage graph and run comparer |
| 0.37.0 | August 26, 2026 | Hierarchical execution spans and a trace inspector |
| 0.43.0 | October 20, 2026 | Compatibility with `huggingface_hub` 2.x |

## Design

### Local storage

Trackio stores each project in its own SQLite database file (`{project}.db`) in a directory set by the `TRACKIO_DIR` environment variable, which defaults to `~/.cache/huggingface/trackio`. Tables include `metrics`, `configs`, `system_metrics` and `traces`; metric values are stored as JSON blobs keyed by run and step. Media and uploaded files are kept under a `media/` subdirectory. When syncing to Hugging Face, Trackio exports the SQLite data to Parquet files before upload.[11]

According to the README, `trackio.log()` is non-blocking: it appends entries to an in-memory queue, and a background thread writes them to SQLite every 0.5 seconds. The project says failures inside Trackio's logging paths are designed to degrade to warnings and local buffering rather than raise exceptions in the user's training loop.[1]

### Hugging Face Spaces and storage

Passing a `space_id` to `trackio.init()` makes Trackio use an existing [Hugging Face](https://aiwiki.ai/wiki/hugging_face) Space or deploy a new one, and send logs there. Spaces can be public or private, so a dashboard can be shared publicly or only within a Hugging Face organization. Locally logged projects can later be uploaded with `trackio.sync()`.[2][12]

The persistence layer has changed since launch. The July 2025 announcement said that a Space's SQLite database is ephemeral and is reset when the Space restarts, so Trackio converted it to a Parquet dataset and backed it up to a Hugging Face Dataset every five minutes.[2] Hugging Face introduced Storage Buckets, described as mutable, S3-like object storage on the Hub, on March 10, 2026.[13] Trackio 0.21.0 switched its backend to Buckets and deprecated the dataset backend, and 0.33.0 again marked persistence to HF Datasets as deprecated.[10] The current documentation says logs persist in a Hugging Face Bucket when using Spaces, and that the `dataset_id` option will be removed in a future version in favor of `bucket_id`.[8]

Besides the default Gradio Space with a live server, Trackio can deploy a static Space that reads Parquet files from a Bucket and runs entirely in the browser. Static Spaces are read-only and require public snapshot data. A `trackio.freeze()` function creates a one-time static snapshot of a project from a live Space.[12]

### Self-hosting and embedding

A Trackio dashboard and API can also run on the user's own infrastructure, with training jobs pointed at it through `server_url` or the `TRACKIO_SERVER_URL` environment variable and authenticated with a Trackio write token. If both a Space and a server URL are configured, the Space takes precedence.[1]

Dashboards hosted on Spaces can be embedded in other web pages as iframes. URL query parameters select a project and metrics, hide the sidebar, set the x-axis and zoom range, and set the smoothing value.[1][12]

The README describes the backend as Python and the built-in dashboard as Svelte 5, with UI controls adapted from Gradio's component source, and says the project is designed to be forked.[1]

## API and features

The core API mirrors `wandb.init`, `wandb.log` and `wandb.finish`, which is why the project suggests `import trackio as wandb` for existing code. The migration guide says the same syntax covers tables, images, audio and 3D objects, and it also shows how to port code written for Neptune.[2][14]

| Area | What the documentation describes |
|---|---|
| Logging | Scalars, configs, tables, images, video, audio, 3D objects, histograms, HTML and Plotly or Matplotlib figures[10][15] |
| System metrics | NVIDIA GPU monitoring, Apple Silicon monitoring, and CPU, RAM, disk and network metrics[15][10] |
| Alerts | `trackio.alert()` with levels; alerts are printed, stored, shown in the dashboard and optionally sent to Slack, Discord or other webhooks[1] |
| Artifacts | Versioned file collections with `log_artifact` and `use_artifact`, a registry and a lineage graph[10] |
| Command line | `trackio show`, `sync`, `freeze`, `list`, `get`, and read-only SQL through `trackio query`[1][11] |
| Imports | Functions to import CSV files and TensorFlow event files (as written by [TensorBoard](https://aiwiki.ai/wiki/tensorboard))[16] |
| MCP | An optional [Model Context Protocol](https://aiwiki.ai/wiki/model_context_protocol) server mode that exposes project, run and metric inspection tools, plus write-token-gated mutation tools[17] |

The project positions Trackio for use by [AI agents](https://aiwiki.ai/wiki/ai_agents) as well as people. The README argues that a local SQLite store with a command-line query interface suits LLM-driven analysis of experiment data.[1] The README also contains a feature comparison table against Weights & Biases written by the Trackio project; its main claimed difference is that Trackio is free for unlimited personal and team use.[1]

The README reports throughput figures measured by the project against a free-tier Space (2 vCPU, 16 GB RAM): 2,000 logs from a single run delivered in under 8 seconds, and 32,000 logs from 32 parallel threads delivered in about 14 seconds. These are self-reported measurements.[1]

## Integrations

| Library or tool | How Trackio is used | Source |
|---|---|---|
| [Transformers](https://aiwiki.ai/wiki/transformers) | `TrainingArguments(report_to="trackio")`, with optional `project` and `trackio_space_id`; Trackio docs require 4.54.0 or later | [6][18] |
| [Accelerate](https://github.com/huggingface/accelerate) | `Accelerator(log_with="trackio")`, added in 1.9.0 | [5][2] |
| [TRL](https://aiwiki.ai/wiki/huggingface_trl) | `report_to="trackio"` in trainer configs such as `SFTConfig`, `DPOConfig` and `GRPOConfig`; Trackio docs require 1.2.0 or later | [19] |
| OpenResearch | alphaXiv's research-agent workspace logs runs to Trackio | [20][21] |

In Transformers, the integration lives in a `TrackioCallback` class. It can add a link to the Trackio Space and Trackio tags to a model's model card.[22] TRL release notes record further Trackio work, including completions logging in `GRPOTrainer` (0.25.0), model card visualization (0.29.0) and recording rollout traces (1.10.0).[23]

On October 23, 2026, alphaXiv announced that [OpenResearch](https://aiwiki.ai/wiki/openresearch) "now has @TrackioApp built in", saying an agent logs its experiments to Trackio, its charts open next to each run, and the agent reads the curves back to decide what to try next.[20] The corresponding pull request in the OpenResearch repository, merged on October 22, 2026, adds support for `TRACKIO_SPACE_ID`, passes Trackio settings to Hugging Face Jobs, starts `trackio show` on demand for local runs, adds a Visualize view that embeds a run's Trackio charts, and adds an `orx metrics` command that summarizes logged curves for agents.[21]

## Development status

The README states that Trackio is in pre-release and may ship breaking changes, particularly to the SQLite schema. It also says the maintainers have paused accepting pull requests from outside the Trackio maintainer team and ask for detailed issues instead. As of October 25, 2026, the GitHub repository had 1,735 stars and 167 forks.[1][4]

## See also

- [Weights & Biases](https://aiwiki.ai/wiki/wandb)
- [MLflow](https://aiwiki.ai/wiki/mlflow)
- [TensorBoard](https://aiwiki.ai/wiki/tensorboard)
- [MLOps](https://aiwiki.ai/wiki/mlops)
- [Gradio](https://aiwiki.ai/wiki/gradio)

## References

1. Trackio README, GitHub (gradio-app/trackio). https://github.com/gradio-app/trackio. Accessed October 25, 2026.
2. Abubakar Abid, Zach Nation, Nouamane Tazi, Sasha Luccioni, Quentin Gallouédec. "Introducing Trackio: A Lightweight Experiment Tracking Library from Hugging Face." Hugging Face Blog, July 29, 2025. https://huggingface.co/blog/trackio
3. "trackio" package and release history. PyPI. https://pypi.org/project/trackio/. Accessed October 25, 2026.
4. gradio-app/trackio repository metadata and contributors. GitHub. https://github.com/gradio-app/trackio. Accessed October 25, 2026.
5. "v1.9.0" release notes. huggingface/accelerate, GitHub, July 16, 2025. https://github.com/huggingface/accelerate/releases/tag/v1.9.0
6. "v4.54.0" release notes. huggingface/transformers, GitHub, July 25, 2025. https://github.com/huggingface/transformers/releases/tag/v4.54.0
7. Robert Krzaczyński. "Hugging Face Releases Trackio, a Lightweight Open-Source Experiment Tracking Library." InfoQ, September 2, 2025. https://www.infoq.com/news/2025/09/hugging-face-trackio/
8. "Trackio" documentation index. Hugging Face. https://huggingface.co/docs/trackio/index. Accessed October 25, 2026.
9. @TrackioApp profile. X. https://x.com/TrackioApp. Accessed October 25, 2026.
10. Trackio CHANGELOG. GitHub (gradio-app/trackio). https://github.com/gradio-app/trackio/blob/main/CHANGELOG.md. Accessed October 25, 2026.
11. "Storage Schema and Direct Queries." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/storage_schema
12. "Deploying and Embedding Dashboards." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/deploy_embed
13. "Introducing Storage Buckets on the Hugging Face Hub." Hugging Face Blog, March 10, 2026. https://huggingface.co/blog/storage-buckets
14. "Migrating to Trackio." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/migration
15. "Track." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/track
16. trackio/imports.py (`import_csv`, `import_tf_events`). GitHub (gradio-app/trackio). https://github.com/gradio-app/trackio/blob/main/trackio/imports.py
17. "Trackio as an API and MCP Server." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/api_mcp_server
18. "Transformers Integration." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/transformers_integration
19. "TRL Integration." Trackio documentation, Hugging Face. https://huggingface.co/docs/trackio/trl_integration
20. alphaXiv (@askalphaxiv). Post announcing Trackio in OpenResearch. X, October 23, 2026. https://x.com/askalphaxiv/status/2113643607949234549
21. "Trackio: Spaces, hf runs, zero-setup local, Visualize view, and orx metrics (#756)." alphaXiv/OpenResearch, GitHub, October 22, 2026. https://github.com/alphaXiv/OpenResearch/commit/dceecf929a97f56a9d2a9f0dac3099e08825a247
22. transformers/integrations/integration_utils.py (`TrackioCallback`). huggingface/transformers, GitHub. https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py
23. TRL release notes (v0.25.0, v0.29.0, v1.10.0). huggingface/trl, GitHub. https://github.com/huggingface/trl/releases