Install & Compatibility
Where this runs
tested against v0.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 3.028s · 728MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 13.5s · import 1.413s · 324MB
504MB installed
● package 504MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
trackio
✓ import trackio
✗ from trackio import init, log
The primary interaction is through the main 'trackio' module, often aliased as 'wandb' for compatibility.
wandb_alias
✓ import trackio as wandb
For direct compatibility with existing Weights & Biases codebases, `trackio` can be imported as `wandb`.
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`.
import trackio
import random
import time
import os
# Initialize a new experiment run
# For Spaces integration, add space_id='your_username/your_space_name'
run = trackio.init(project="my-awesome-project",
name=f"run-{int(time.time())}",
config={
"learning_rate": 0.001,
"epochs": 5,
"batch_size": 32
})
print(f"Starting run: {run.name} in project: {run.project_name}")
# Simulate a training loop
for epoch in range(run.config["epochs"]):
# Simulate metrics
train_loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1)
val_loss = 0.8 / (epoch + 1) + random.uniform(-0.05, 0.05)
accuracy = 0.5 + (epoch / run.config["epochs"]) * 0.4 + random.uniform(-0.03, 0.03)
# Log metrics
trackio.log({"epoch": epoch, "train_loss": train_loss, "val_loss": val_loss, "accuracy": accuracy})
print(f"Epoch {epoch}: Train Loss = {train_loss:.4f}, Val Loss = {val_loss:.4f}, Accuracy = {accuracy:.4f}")
time.sleep(0.5)
# Finish the run
trackio.finish()
print("Run finished. To view the dashboard, run `trackio show` in your terminal.")
trackio --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'trackio'
The trackio library has not been installed in your current Python environment.
NameError: name 'wandb' is not defined
You attempted to use wandb-compatible functions (like wandb.init()) after importing trackio, but without aliasing 'trackio.wandb' as 'wandb'.
fixReplace 'import wandb' with 'import trackio.wandb as wandb' in your code.
AttributeError: module 'trackio' has no attribute 'init'
You are trying to call wandb-compatible functions directly from the top-level 'trackio' module, instead of through 'trackio.wandb'.
fixAccess wandb-compatible functions by aliasing 'trackio.wandb': 'import trackio.wandb as wandb; wandb.init(...)'
sqlite3.OperationalError: unable to open database file
Trackio failed to open or create its local SQLite database, typically due to insufficient file permissions in the specified 'log_dir' or an invalid directory path.
fixEnsure the directory where trackio attempts to store its SQLite database (default: 'runs/' in the current working directory, or specified by 'log_dir' in 'trackio.configure()') exists and has proper read/write permissions for the running process.
Upgrade
Version history
0.37.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
nvidia-smioptionalFor logging NVIDIA GPU metrics; optional with `[gpu]` extra.
py-apple-gpuoptionalFor logging Apple M-series CPU/GPU/system metrics; optional with `[apple-gpu]` extra.
tensorboardoptionalFor importing TensorBoard event files; optional with `[tensorboard]` extra.
huggingface_huboptionalFor interacting with Hugging Face Hub (Spaces, Datasets); implicitly used when `space_id` is provided.
gradiorequiredUsed for the local dashboard UI.