{"id":4287,"library":"trackio","title":"trackio","description":"Trackio is a lightweight, local-first, and free experiment tracking library built by Hugging Face. It offers an API compatible with Weights & Biases (wandb) for seamless migration, allowing users to log metrics, parameters, and artifacts. Logs are persisted locally in an SQLite database and can be optionally synced with Hugging Face Datasets and visualized on Hugging Face Spaces. It is actively developed with a focus on simplicity, extensibility, and LLM-friendly programmatic access.","status":"active","version":"0.22.0","language":"en","source_language":"en","source_url":"https://github.com/gradio-app/trackio","tags":["experiment tracking","machine learning","hugging face","wandb-alternative","local-first","mlops"],"install":[{"cmd":"pip install trackio","lang":"bash","label":"Default Install"},{"cmd":"pip install trackio[gpu]","lang":"bash","label":"GPU Monitoring (NVIDIA)"},{"cmd":"pip install trackio[apple-gpu]","lang":"bash","label":"System Monitoring (Apple Silicon)"},{"cmd":"pip install trackio[tensorboard]","lang":"bash","label":"TensorBoard Import"},{"cmd":"pip install trackio[dev]","lang":"bash","label":"Development Install"},{"cmd":"pip install trackio[spaces]","lang":"bash","label":"Hugging Face Spaces Integration"}],"dependencies":[{"reason":"For logging NVIDIA GPU metrics; optional with `[gpu]` extra.","package":"nvidia-smi","optional":true},{"reason":"For logging Apple M-series CPU/GPU/system metrics; optional with `[apple-gpu]` extra.","package":"py-apple-gpu","optional":true},{"reason":"For importing TensorBoard event files; optional with `[tensorboard]` extra.","package":"tensorboard","optional":true},{"reason":"For interacting with Hugging Face Hub (Spaces, Datasets); implicitly used when `space_id` is provided.","package":"huggingface_hub","optional":true},{"reason":"Used for the local dashboard UI.","package":"gradio","optional":false}],"imports":[{"note":"The primary interaction is through the main 'trackio' module, often aliased as 'wandb' for compatibility.","wrong":"from trackio import init, log","symbol":"trackio","correct":"import trackio"},{"note":"For direct compatibility with existing Weights & Biases codebases, `trackio` can be imported as `wandb`.","symbol":"wandb_alias","correct":"import trackio as wandb"}],"quickstart":{"code":"import trackio\nimport random\nimport time\nimport os\n\n# Initialize a new experiment run\n# For Spaces integration, add space_id='your_username/your_space_name'\nrun = trackio.init(project=\"my-awesome-project\", \n                   name=f\"run-{int(time.time())}\",\n                   config={\n                       \"learning_rate\": 0.001,\n                       \"epochs\": 5,\n                       \"batch_size\": 32\n                   })\n\nprint(f\"Starting run: {run.name} in project: {run.project_name}\")\n\n# Simulate a training loop\nfor epoch in range(run.config[\"epochs\"]):\n    # Simulate metrics\n    train_loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1)\n    val_loss = 0.8 / (epoch + 1) + random.uniform(-0.05, 0.05)\n    accuracy = 0.5 + (epoch / run.config[\"epochs\"]) * 0.4 + random.uniform(-0.03, 0.03)\n    \n    # Log metrics\n    trackio.log({\"epoch\": epoch, \"train_loss\": train_loss, \"val_loss\": val_loss, \"accuracy\": accuracy})\n    print(f\"Epoch {epoch}: Train Loss = {train_loss:.4f}, Val Loss = {val_loss:.4f}, Accuracy = {accuracy:.4f}\")\n    time.sleep(0.5)\n\n# Finish the run\ntrackio.finish()\nprint(\"Run finished. To view the dashboard, run `trackio show` in your terminal.\")","lang":"python","description":"This quickstart demonstrates how to initialize a tracking run, log metrics within a simulated training loop, and finalize the run. It uses `trackio.init` to set up the project and configuration, `trackio.log` to record scalar metrics, and `trackio.finish` to conclude the experiment. To view the collected metrics, open a new terminal and run `trackio show`."},"warnings":[{"fix":"Be prepared to delete or migrate local database files when updating to new major/minor versions. Consult release notes for migration instructions.","message":"Trackio is currently in beta, and its SQLite database schema may change in future releases. This could necessitate migrating or deleting existing database files (located by default at `~/.cache/huggingface/trackio`) to maintain compatibility.","severity":"breaking","affected_versions":"<=0.22.0"},{"fix":"Always call `trackio.init()` once per experiment run to establish the tracking environment.","message":"The `trackio.init()` function must be called at the beginning of your script or experiment run before any other `trackio` logging functions (`log`, `save`, etc.) are used. Failing to do so will result in errors as the tracking context will not be established.","severity":"gotcha","affected_versions":"All"},{"fix":"Review the official Trackio documentation for supported features if migrating from `wandb` or expecting specific advanced functionalities.","message":"While Trackio provides API compatibility with `wandb`, it is intentionally lightweight and does not yet support all advanced features found in Weights & Biases, such as artifact versioning, comprehensive custom visualizations, or advanced sweeps management.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure you are logged in via `huggingface-cli login` and your token has the necessary write access before initializing runs with `space_id`.","message":"When using `space_id` in `trackio.init()` to sync logs to Hugging Face Spaces, your local `huggingface-cli` must be logged in and configured with a token that has write permissions for the specified Space or to create a new one.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}