Trackio stores runs in SQLite so an agent can query them with SQL instead of a dashboard

The migration path is one import line

The compatibility claim is narrow and specific: the API matches wandb.init, wandb.log and wandb.finish. In most cases the usage is designed to be identical, so switching is an alias.

import trackio as wandb

Keep the existing logging code and it works. That is a genuine advantage over trackers that require restructuring, because the risk of a migration is concentrated in one line rather than spread through a training script.

It is also the limit of the claim. Three functions are named, and anything else in the wandb surface, sweeps, artifacts, integrations, the config system beyond what init takes, is not covered by that promise. A script that uses more than init, log and finish is doing more work than an import swap.

The library requires Python 3.10 or higher and installs with pip or uv. It is published as trackio on PyPI, built with hatchling, and declares huggingface-hub, gradio-client, starlette and uvicorn among its dependencies, which is a hint about what runs the dashboard rather than what records the metrics.

SQLite storage is the decision everything else follows from

The README gives the reason for local-first as a practical one: you should not need to make an account to log data. But the storage choice does more than remove the signup.

Logs are stored in a SQLite database, with support for freezing logs to Parquet. SQLite is what allows very high throughput for parallel experiments, since writers append locally and a training job is not making network round trips per metric. That is the property that matters if you run many experiments at once on one machine or across a few GPUs.

It is also what makes the SQL interface possible. The CLI exposes read-only SQL directly against the data:

trackio query project --project <name> --sql "SELECT ..."

The documented position is that trackio list and trackio get cover the common cases and the SQL escape hatch is there when they are not enough. The storage schema and a direct query reference are published as separate documentation, which tells you the schema is intended to be relied on rather than treated as an implementation detail.

Parquet freezing matters for the same reason. Once a run is finished and no longer being appended to, converting it to a columnar file makes it cheap to read in bulk, which is the operation an analysis pass does.

Designed for agents, and the dashboard is the fallback

The README is explicit about the audience: a library built by Hugging Face for humans and AI agents, with a CLI for programmatic access and a Python API for run management.

The reasoning is that an agent cannot use a dashboard. It can run a CLI and it can read SQL, so the interface a model needs to answer a question about last night's experiment is the same one a script uses. The Gradio-inspired dashboard exists for the human case, and it is described as also shipped rather than as the product.

What the dashboard shows is metrics, media, tables and alerts. The examples directory shows how wide that is in practice: there are scripts for images, HTML, video, audio synthesis, Object3D content, grouped runs, many runs, and heavy logging patterns such as fake-training-heavy-logging.py and fake-training-many-runs.py, which are the ones to read before you log at scale.

Alerts have an example that posts to a Slack webhook. Files and artifacts are covered by examples that deploy on Spaces and import from CSV.

The optional dependency groups in pyproject.toml show the same spread: a tensorboard group for importing from tbparse and tensorboardX, a gpu group with nvidia-ml-py and psutil for system metrics, an apple-gpu group, and an mcp group.

Three destinations, and the precedence between them is documented

A run can end up in one of three places, and the order of precedence is stated rather than left to be discovered.

By default, init runs the service locally and stores project data on the local machine. No destination argument is the local case.

Passing space_id to init points the run at a Hugging Face Space, using an existing one or deploying a new one as needed. You must be logged in with huggingface-cli locally and the token needs write permission to create the Space. All dashboards can also be viewed together at trackio-laboratory.hf.space.

Passing server_url points the client at a server you run yourself, over HTTP, so training jobs can write to a shared instance without the data leaving your infrastructure.

trackio.init(project="my-project", server_url="http://127.0.0.1:7860?write_token=YOUR_TOKEN")

Authentication for that path is a separate thing from your Hugging Face token. The client sends a write token, which may arrive as a write_token query parameter on the URL or through the TRACKIO_WRITE_TOKEN environment variable. If you would rather set the token on the server at launch than let it be generated, you set TRACKIO_WRITE_TOKEN before starting the server. TRACKIO_SERVER_URL does the same job for the address, and TRACKIO_SPACE_ID exists for the Space case.

The conflict rule is explicit: if space_id or TRACKIO_SPACE_ID and server_url or TRACKIO_SERVER_URL are both set, Trackio uses the Space and ignores the self-hosted URL. That is a footgun worth knowing before you wire both into an environment.

Where Trackio is the wrong choice

The clearest case against is the collaboration story. The default is a SQLite file on your machine, which is excellent for one person or one cluster and awkward for a team that needs a shared view, permissions and a stable URL. A Spaces deployment addresses that and puts your run data on Hugging Face infrastructure, which is a different decision from a self-hosted server.

The second is scale of ingestion. The high throughput claim is about parallel experiments writing locally. If your workload is one job logging a very large number of very small metrics per second, the practical question is what the dashboard does with them, and the heavy-logging example is where to look before you commit.

The third is dependency surface. Installing trackio pulls in gradio-client, starlette and uvicorn with the standard extra, because the dashboard is a web server that ships with the library. If you only want to write metrics to a file in a minimal training environment, that is a lot of package for the job, and writing JSON lines yourself is smaller.

Compared with wandb itself, the difference in approach is where the data lives and who can query it: local SQL and a CLI on one side, a hosted service with a richer feature set on the other. If you rely on anything beyond the three mirrored functions, you are trading features for local control.

The alternative worth weighing for a team is a hosted tracker you self-host, which gives shared access without putting runs on a vendor's infrastructure, at the cost of running the service. Trackio's self-hosted server mode is the local version of that idea, and it is the mode to evaluate first if the SQLite default is what stops you.

On versions and licence: the recent tags are 0.42.0, 0.41.0 and 0.40.0 across September and October 2026, so releases are frequent, the last push was on 2026-10-15, and the licence is MIT.

Editorial conclusion

Adopt Trackio if you want wandb-shaped logging without an account and your analysis is scripted or agent-driven, since read-only SQL over a local SQLite file is the reason it exists. Do not adopt it as a team-scale hosted tracker without reading the self-hosted server notes. Before switching, check that your code only uses init, log and finish, since that is the documented API compatibility surface.

Frequently asked questions

Official sources

1. gradio-app/trackio on GitHub
2. Issues
3. License: MIT
4. README
5. Releases