Quickstart

This page gives you a practical, minimal path to get WeightsLab running. If you prefer to start from examples, see Examples right after this setup.

Prerequisites

  • Python v3.10+ installed

  • A virtual environment tool like venv or Conda (optional).

  • Your training project available locally.

Install WeightsLab

Create and activate a virtual environment and install WeightsLab.

python -m pip install weightslab

Tip

For reproducible experiments, you can install in a virtual environment with the following command:

# From the repository root
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# Linux/macOS
# source .venv/bin/activate

Try the bundled example

To see WeightsLab working end to end without writing any code, start one of the bundled examples (–cls, –seg, –det, –2d_det, –3d_det). It run a small bundled experiment:

weightslab start example --cls

Then, in another terminal, launch the UI and open the URL printed by the command:

weightslab start

Local integration in your own Python script (MNIST)

Below is your MNIST CNN training pattern, first instrumented with TensorBoard, then with TensorBoard removed and replaced by WeightsLab.

 1import torch
 2import torch.nn as nn
 3import torch.optim as optim
 4-  from torch.utils.tensorboard import SummaryWriter
 5from torchvision import datasets, transforms
 6+  import weightslab as wl
 7
 8
 9class CNN(nn.Module):
10    def __init__(self):
11        super().__init__()
12+          self.input_shape = (1, 28, 28)  # Weightslab necessary input shape for MNIST
13        self.net = nn.Sequential(
14            nn.Conv2d(1, 32, 3, padding=1),
15            nn.ReLU(),
16            nn.MaxPool2d(2),
17            nn.Conv2d(32, 64, 3, padding=1),
18            nn.ReLU(),
19            nn.MaxPool2d(2),
20            nn.Flatten(),
21            nn.Linear(64 * 7 * 7, 10),
22        )
23
24    def forward(self, x):
25        return self.net(x)
26
27
28cfg = {
29    "device": "auto",
30    "data_root": "./data",
31    "data": {
32        "train_loader": {
33            "batch_size": 64,
34        }
35    },
36    "optimizer": {
37        "lr": 1e-3,
38    },
39}
40device = "cuda" if torch.cuda.is_available() and cfg["device"] in ["auto", "cuda"] else "cpu"
41
42train_ds = datasets.MNIST(cfg["data_root"], train=True, download=True, transform=transforms.ToTensor())
43train_loader = torch.utils.data.DataLoader(train_ds, batch_size=cfg["data"]["train_loader"]["batch_size"], shuffle=True)
44
45model = CNN().to(device)
46optimizer = optim.Adam(model.parameters(), lr=cfg.get("optimizer", {}).get("lr", 1e-3))
47loss = nn.CrossEntropyLoss(reduction="none")
48-  writer = SummaryWriter(log_dir="./runs/mnist_baseline")
49+
50+ # Wrap your objects with WeightsLab to watch and edit them in real time.
51+ ## Wrap the hyperparameters first
52+  hp = wl.watch_or_edit(cfg, flag="hyperparameters")
53+
54+ ## Wrap the model and optimizer next
55+  model = wl.watch_or_edit(model, flag="model", device=device)
56+  optimizer = wl.watch_or_edit(
57+      optimizer,
58+      flag="optimizer",
59+  )
60+
61+ ## Then wrap the loss and metrics functions
62+  loss = wl.watch_or_edit(
63+      loss,
64+      flag="loss",
65+      signal_name="train/loss",
66+      per_sample=True,
67+      log=True,
68+  )
69+  train_loader = wl.watch_or_edit(
70+      train_ds,
71+      flag="data",
72+      loader_name="train_loader",
73+      batch_size=cfg["data"]["train_loader"]["batch_size"],
74+      shuffle=True,
75+      is_training=True,
76+  )
77+
78+ # Finally start the WeightsLab backend and keep it running while you train.
79+  wl.serve(serving_grpc=True, serving_cli=True)
80
81step = 0
82while 1:
83+      with wl.guard_training_context:
84-      inputs, labels = next(iter(train_loader))
85+             inputs, uids, labels, metadata = next(iter(train_loader))
86           inputs, labels = inputs.to(device), labels.to(device)
87           optimizer.zero_grad()
88           logits = model(inputs)
89-          loss_per_sample = loss(logits, labels)
90+             loss_per_sample = loss(logits, labels, batch_ids=uids, preds=logits)
91           loss_per_sample.mean().backward()
92           optimizer.step()
93   if step % 20 == 0:
94      print(f"Loss: {loss_per_sample.mean().item():.4f}")
95   step += 1
96
97-  writer.close()
98+  wl.keep_serving()

Notebook Code with Google Colab

Start by opening this notebook:

Use Weightslab Studio (UI)

For a full visual experiment monitoring workflow (agent, samples, tags, discard/restore, plots), deploy the Weights Studio web app with the bundled CLI.

By default the UI runs unsecured (HTTP, no gRPC auth) — no certificates are generated. Pass --certs to generate (if missing) and use TLS certificates + a gRPC auth token:

weightslab start              # unsecured HTTP (default)
weightslab start --certs      # secured HTTPS + gRPC auth (run `weightslab se` first)

Important

When using certs, it is prefered to set manually the WEIGHTSLAB_CERTS_DIR environment variable so the training backend and any new terminal use the same certificates — it is the single source of truth for TLS/auth. Please note that this step has to be done before starting the experiment.

Run weightslab, weightslab help, or weightslab -h to see the banner and the full command reference (se, start, start example ...).

To stop the UI, press Ctrl+C in the terminal running weightslab start.

Prefer a terminal over a browser? weightslab cli opens an interactive console connected to the running experiment (pause/resume, status, evaluate, tag/discard samples, query the agent, …) — no UI container required:

weightslab cli

Full reference for both — every weightslab subcommand and every console command, with all flags and defaults — lives in User Commands Reference.

Tip

Let an AI agent integrate WeightsLab for you.

The repository ships with AGENTS.md — a compact context file that gives any AI coding assistant (Claude, Copilot, Cursor, …) a complete picture of the WeightsLab API. Open your training script, attach AGENTS.md as context, and ask:

"Using the context in AGENTS.md, integrate WeightsLab into this training script."

The agent will wire up your model, data loader, loss, and hyperparameters in a few edits — no manual API lookup needed. Otherwise use the Agent Quickstart to connect the integrated OpenCode agent to a running experiment and have it generate code for you from the UI.