Trackio

Trackio is an open-source experiment tracking library for Python developed by 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, 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.^[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 1.9.0 (July 16, 2025) added a Trackio tracker, and 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, 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]

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 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]

The project positions Trackio for use by 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

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 "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
• MLflow
• TensorBoard
• MLOps
• Gradio

References

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