Quickstart

This page gives you a practical, minimal path to get WeightsLab running. If you prefer to start from examples, see usecases 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.

# From the repository root
python -m venv .venv

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

python -m pip install weightslab

Try the bundled example

To see WeightsLab working end to end without writing any code, start a bundled example like the classification example (–cls). It run a small experiment on a classification task:

weightslab start example --cls

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

weightslab start

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.