wandb Cheat Sheet

01Install & authenticateonce per machine

pip install wandb
Python 3.10+ and pydantic ≥ 2.6 since 0.27.0.
pip install wandb[media]
Extra codecs for logging video, audio and 3D objects.
wandb login
Interactive. Stores the key in ~/.netrc, so you never do it again on that box.
wandb.login(key=..., relogin=True)
From inside Python. relogin=True forces a fresh key over a cached one.
export WANDB_API_KEY=...
The right way in CI and containers — no interactive prompt, no netrc.
wandb login --host https://wandb.acme.com
Point at a self-hosted or dedicated W&B Server instead of the public cloud.
wandb login --verify
Confirms the stored credentials actually work before a long job starts.

02The CLIwandb --help

wandb sync ./wandb/offline-run-...
Uploads a run recorded offline. The whole point of offline mode.
wandb offline · wandb online
Flips the default mode for every subsequent run in this directory.
wandb sweep sweep.yaml
Registers the sweep and prints the sweep ID you feed to agents.
wandb agent entity/project/SWEEP_ID
Starts a worker. Run it on as many machines as you like — they coordinate through the controller.
wandb artifact put ./data -n dataset -t dataset
Upload an artifact without writing any Python.
wandb artifact cache cleanup 1GB
The local artifact cache grows without bound. This is the fix when the disk fills.
wandb leetGA 0.28.0
Terminal dashboard for live runs. Was wandb beta leet before 0.28.0.
wandb status · wandb verify
Show current settings; check connectivity to the host.

03Environment variablesfor CI & containers

WANDB_API_KEY
Authentication without an interactive login.
WANDB_PROJECT · WANDB_ENTITY
Defaults for init(), so the same script works across teams unchanged.
WANDB_MODE=offline|disabled
offline records to disk for later sync; disabled turns every call into a no-op — ideal for unit tests.
WANDB_RUN_ID
Set it yourself to make a job resumable after a pre-emption.
WANDB_NAME · WANDB_NOTES · WANDB_TAGS
Display name, free-text notes, comma-separated tags.
WANDB_RUN_GROUP
Groups distributed workers or CV folds into one logical experiment.
WANDB_DIR
Where the local wandb/ folder goes. Point it at scratch on a cluster.
WANDB_CACHE_DIR · WANDB_DATA_DIR
Artifact cache and staging locations — the two that fill up shared home directories.
WANDB_SILENT=true
Suppresses the banner and progress output in notebooks and logs.
WANDB_DISABLE_CODE=true
Stops code and git state being saved, for when the repo cannot leave the building.
SINGULARITYENV_* / APPTAINERENV_*
Prefix to pass any of the above through into a Singularity/Apptainer container.

04Start a run★init returns a Run

with wandb.init(project="p") as run:
The recommended form. Flushes and closes on exit — and marks the run failed if the block raises.
run = wandb.init(...) # ... run.finish()
Manual form. You must call finish() yourself, or the run sits "running" forever.
run.log({"acc": 0.9})
Log on the object, not the module. This is the single biggest change from older tutorials.
run.finish(exit_code=1)
Mark a run failed deliberately — useful in your own exception handler.
wandb.setup()
Call once in the parent before forking, so multiple processes share one service.
# run names cannot contain / \ # ? % :
These break the URL. Same restriction applies to artifact names.

05wandb.init() parameters★the ones that matter

project="my-project", entity="my-team"
Where the run lands. Entity defaults to your personal account.
config={"lr": 3e-4}
The inputs. Everything you would want to group or filter by later belongs here.
name="resnet-baseline", notes="..."
Human label and free text. Omit name and W&B invents a memorable one.
tags=["baseline", "v2"]
Filterable labels. Cheaper to reorganise later than project names.
mode="online"|"offline"|"disabled"|"shared"
shared lets several processes write to one run — the distributed-training option.
id=..., resume="allow"
The resumable pair. See card 07.
group=..., job_type="train"
Two-level organisation for runs that belong together.
save_code=True
Snapshots the main script and git state so a result stays reproducible.
sync_tensorboard=True
Mirrors existing TensorBoard writes into W&B without touching your training code.
dir=..., settings=wandb.Settings(...)
Local output directory, and the escape hatch for everything else.
reinit="create_new"
Multiple concurrent runs in one process. Replaces the old boolean reinit=True.

06The Run objectwhat init hands back

run.id · run.name · run.project · run.entity
Identity. run.id is what you keep to resume later.
run.url
Link to the run page. Was run.get_url() in older code.
run.config · run.summary
Both read/write dict-likes. Config is the input, summary the headline result.
run.step
The current history step. Read-only, monotonic.
run.resumed
True if this init() picked up an existing run — branch your warm-start logic on it.
run.tags += ("new-tag",)
Tags are a tuple. Concatenate; you cannot append.
run.alert(title=..., text=..., level="WARN")
Sends email/Slack. Perfect for a NaN loss guard on a long job.
run.save("out/*.txt", policy="live")
Sync matching files as they change. Policies: live, now, end.
run.log_code()
Explicitly snapshot source when save_code was off.
run.mark_preempting()
Tells W&B a spot instance is going away, so the run is requeued rather than marked crashed.
run.write_logs(text)0.27.0
Push arbitrary text into the run's log stream.
run.pin_config_keys(["lr", "arch"])0.26.0
Pins those keys to the front of the runs table in the UI.

07Resume, fork, rewindthree different things

wandb.init(id=rid, resume="allow")
Resume: continue the same run, appending to its history. Needs the original id.
resume="must"|"allow"|"never"
must errors if the run is missing, never errors if it exists. must is the safe choice for pre-emptible jobs.
wandb.init(fork_from=f"{rid}?_step=200")
Fork: a brand-new run branching off an existing one at a step. The original is untouched.
wandb.init(resume_from=f"{rid}?_step=200")
Rewind: same run id, history truncated back to that step. Use it to erase a diverged tail.
run.mark_preempting() + resume="must"
The standard spot-instance pattern: signal on the way out, resume on the way back in.
# step can never go backwards
Which is exactly why rewind exists — you cannot simply re-log an earlier step.

08Organising many runsbefore you have 500

wandb.init(group="cv-fold-sweep")
Collapses related runs into one row that expands. The fix for cross-validation clutter.
wandb.init(job_type="eval")
Second axis within a group: preprocess, train, eval.
wandb.init(tags=["ablation"])
Cross-cutting labels that survive reorganisation.
wandb.init(group=os.environ["SLURM_JOB_ID"])
Ties every worker of one cluster job together automatically.
if rank == 0: run = wandb.init(...)
Simplest distributed pattern: only rank 0 logs. The alternative is mode="shared" from every rank.
run.pin_config_keys(["lr"])
Makes the columns you actually compare visible by default.

09Config — the inputs★write once, read often

wandb.init(config={"lr": 0.01, "bs": 32})
Set it at the top. Anything you might group, filter or sweep over goes here.
cfg = run.config; cfg.lr
Attribute or key access both work. Always read hyperparameters from here — that is what makes the script sweepable.
run.config.update({"n_params": n})
Add values you only learn after the model is built.
wandb.init(config=vars(args))
One line to capture an entire argparse namespace.
wandb.init(config="config.yaml")
Load straight from a YAML file. A bare config-defaults.yaml is picked up automatically.
run.config.update(d, allow_val_change=True)
Reassigning an existing key raises without this flag.
run.config_static
A frozen snapshot — useful when a sweep agent might otherwise mutate it under you.
# keys cannot contain "." · values cap at 10 MB
Dots break the nested-key syntax. Config is for scalars, not datasets.

10run.log() — the core call★one row per call

run.log({"loss": 0.5, "acc": 0.9})
One call writes one history row and advances the step. Batch your keys into a single call.
run.log({"train/loss": l, "val/loss": v})
A single / creates a UI section. Only one level counts — a/b/c still groups under a.
run.log(d, commit=False)
Accumulate into the current row without advancing. The fix for logging train and val from different places.
run.log(d, step=i)
Write to an explicit step. It must be ≥ the current step — history never goes backwards.
run.log({"epoch": e, "loss": l})
Log your own x-axis as an ordinary metric, then point charts at it with define_metric.
run.log({"chart": fig})
Matplotlib figures and Plotly charts log directly, no conversion needed.
wandb.log({...})module-level
The form every old tutorial uses. Logging now lives on the Run object returned by init().
# logging train and val separately doubles your rows
Two log() calls per iteration make two half-empty rows. Use commit=False or one combined call.

11Summary & define_metricthe headline number

run.summary["best_acc"] = 0.94
Summary is what the runs table sorts on. Set it explicitly and you control the leaderboard.
# summary defaults to the LAST logged value
Not the best. If your model overfits at the end, the table shows the overfit number.
run.define_metric("val/acc", summary="max")
The proper fix. Options: min, max, mean, last, none.
run.define_metric("val/loss", step_metric="epoch")
Plot against your own x-axis instead of the internal step counter.
run.define_metric("*", step_metric="epoch")
Glob applies it to every metric at once. Declare it before the loop starts.
run.define_metric("internal/*", hidden=True)
Keeps diagnostics out of the default workspace without dropping them.
summary="best", goal="minimize"deprecated
Replaced by the explicit "min" / "max" values.

12Images, video, audiowrap, then log

run.log({"ex": wandb.Image(arr, caption="pred")})
Accepts a numpy array, PIL image, matplotlib figure or path.
run.log({"ex": [wandb.Image(i) for i in imgs]})
A list becomes a browsable gallery under one key.
wandb.Image(img, masks={"pred": {"mask_data": m, "class_labels": L}})
Segmentation overlays with a toggleable class legend.
wandb.Image(img, boxes={"pred": {"box_data": [...]}})
Bounding boxes, each with a class and optional score.
"domain": "pixel"
Box coordinates are fractional by default. Omit this and pixel coordinates land in the corner.
wandb.Video(arr, fps=4, format="gif")
Array shape is (time, channel, height, width). Needs wandb[media].
wandb.Audio(arr, sample_rate=22050)
Renders an inline player with a waveform.
wandb.Histogram(grads, num_bins=64)
Cheap distribution logging — far lighter than logging the raw tensor.
wandb.Html(s) · wandb.Object3D(pts) · wandb.Molecule(f)
Arbitrary HTML, point clouds and molecular structures.
# caps: <50 images and <100 audio clips per step
Beyond that the extras are silently dropped. Log a sample, not the batch.

13Tablesrows you can query

t = wandb.Table(columns=["id", "img", "pred"], data=rows)
Cells can hold media objects, not just scalars — that is what makes tables good for error analysis.
wandb.Table(dataframe=df)
Straight from pandas.
t.add_data(x, wandb.Image(img), pred)
Append row by row inside an eval loop.
wandb.Table(..., log_mode="IMMUTABLE")0.20.1
Default. Logged once, then frozen.
log_mode="MUTABLE"
Re-log the same table object as it grows; each log replaces the last.
log_mode="INCREMENTAL"
Only new rows are uploaded — the right mode for a long eval loop.
# workspaces render only the last 100 increments
The docs' own fix: log INCREMENTAL during the loop, then one IMMUTABLE table at the end.
wandb.Table.MAX_ROWS # default 10000
Rows past the cap are dropped. Raise it deliberately or sample.

14Custom chartswandb.plot

wandb.plot.line(table, x="step", y="loss", title=...)
All the wandb.plot helpers take a Table and return something you pass to run.log().
wandb.plot.scatter(table, x, y)
Two columns against each other.
wandb.plot.bar(table, label, value)
Categorical comparison — feature importances, per-class counts.
wandb.plot.line_series(xs=..., ys=..., keys=...)
Several lines on one axis without building a table first.
wandb.plot.confusion_matrix(y_true=..., preds=..., class_names=...)
Takes raw arrays directly. The most-used helper in the module.
wandb.plot.roc_curve(y_test, y_probas, labels)
Also pr_curve. Both want probabilities, not hard labels.
wandb.plot_table(vega_spec, table, fields)
Your own Vega-Lite spec when none of the built-ins fit. Module-level since 0.19.0.

15System metrics, logs, offlinewandb.Settings

# CPU, GPU, memory, disk, network logged automatically
No setup. Appears under the System tab — the fastest way to spot a data-loading bottleneck.
WANDB_ENABLE_DCGM_PROFILING=true
Adds detailed NVIDIA DCGM GPU counters like SM occupancy.
# cgroup-aware limits are reported inside containers
So the memory ceiling shown is the container's, not the host's.
wandb.Settings(capture_loggers={"myapp": "INFO"})0.27.0
Pipes your existing Python loggers into the run's log stream.
wandb.Settings(finish_timeout=300)0.27.0
Bounds how long finish() waits for uploads before giving up.
wandb.Settings(x_disable_stats=True)
Turn system monitoring off on a constrained node.
WANDB_MODE=offline → wandb sync
The air-gapped workflow: record locally, upload from a machine that has network.

16Artifacts — create & log★versioned outputs

a = wandb.Artifact(name="cifar", type="dataset")
type is free text but organises the UI. Conventional values: dataset, model, result.
a.add_file("data/train.csv") · a.add_dir("data/")
Content is hashed, so re-logging unchanged files costs nothing.
a.add_reference("s3://bucket/path")
Tracks a pointer instead of uploading. The answer for datasets too big to copy.
a.metadata = {"n_rows": 50000}
Arbitrary JSON stored with the version and searchable later.
run.log_artifact(a, aliases=["best"])
Uploads and links it to this run as an output.
run.log_artifact("./ckpt.pt", name="m", type="model")
Shorthand that builds the Artifact for you.
run.log_artifact(a).wait()0.18.3
Logging became async. Without wait(), the version may not exist when the next line asks for it.
a.ttl = timedelta(days=30)
Automatic expiry — the storage-bill control for per-epoch checkpoints.
run.upsert_artifact() · run.finish_artifact()
Build one artifact incrementally across several distributed runs.

17Artifacts — use & downloadand the lineage

a = run.use_artifact("cifar:latest")
Marks it as an input to this run. That edge is what builds the lineage graph.
path = a.download()
Fetches to a local dir and returns the path. Cached, so a second call is free.
a.download(path_prefix="train/")
Pull only part of a large artifact.
entry = a.get_entry("labels.json"); entry.download()
Single file, without materialising the rest.
# name:v3 is permanent; name:latest moves
Aliases are mutable pointers, version numbers are not. Pin :v3 for anything reproducible.
a.aliases.append("production"); a.save()
Promote a version by moving an alias onto it.
wandb.Api().artifact("ent/proj/name:v2")
Fetch outside a run — in a serving process or a CI job.
run.link_artifact(a, "wandb-registry-model/my-coll")
Publish into the Registry, the cross-project promotion path.
run.log_model() · run.use_model() · run.link_model()
Model-flavoured convenience wrappers over the same machinery.

18Sweeps — the config★YAML or dict

"method": "bayes" # or "grid" | "random"
The only strictly required key. bayes needs a metric; the others do not.
"metric": {"name": "val/acc", "goal": "maximize"}
The name must match a key you actually log(), slashes and all.
"parameters": {"lr": {"values": [1e-3, 1e-4]}}
Discrete choice. Every parameter lives under parameters.
{"min": 1e-5, "max": 1e-1, "distribution": "log_uniform_values"}
Use this for learning rates. Plain uniform wastes most samples at the large end.
{"value": 32}
Pin a constant so it still shows up in each run's config.
"early_terminate": {"type": "hyperband", "min_iter": 3}
Kills unpromising runs at exponentially spaced brackets. Usually the biggest single saving.
"run_cap": 50
Hard stop on total runs. Set it before you leave for the weekend.
"command": ["${env}", "${interpreter}", "${program}", "${args}"]
Override how the agent invokes your script — needed for torchrun or a module entry point.
# grid over a continuous range never terminates
Grid requires values. Combine it with min/max and the sweep runs forever.
# the sweep's project must match the run's project
Otherwise the agent's runs land somewhere the controller cannot see them.

19Sweeps — running themcontroller + agents

sweep_id = wandb.sweep(cfg, project="p")
Registers the search. Returns the id the agents need.
wandb.agent(sweep_id, function=main, count=10)
Runs main up to 10 times. Launch on many machines to parallelise.
def main(): with wandb.init() as run: train(run.config)
Note init() takes no arguments here — the agent injects the config.
# the training function takes no arguments
Read every hyperparameter from run.config, never from a closure or a global.
if __name__ == "__main__": wandb.agent(...)
Required under any multiprocessing start method, or agents re-import and re-spawn.
wandb agent entity/project/SWEEP_ID
The CLI equivalent, for when the entry point is a script rather than a function.
wandb sweep --pause | --resume | --stop | --cancel ID
stop lets running jobs finish; cancel kills them immediately.
wandb.controller(sweep_id)
Drive the search loop yourself when you need custom logic between suggestions.
api.sweep("ent/proj/id").best_run()
Pull the winner back out programmatically once it finishes.

20Framework hooksintegrations

run.watch(model, log="all", log_freq=100)
PyTorch gradient and parameter histograms. log: gradients, parameters, all, None.
run.unwatch(model)
Detaches the hooks. Leaving watch on all training is a real slowdown.
from lightning.pytorch.loggers import WandbLogger
Pass as Trainer(logger=WandbLogger(project="p")).
TrainingArguments(report_to="wandb")
HuggingFace Transformers. One argument, nothing else to wire up.
from wandb.integration.keras import WandbMetricsLogger
Per-epoch and per-batch metrics for Keras 3.
WandbModelCheckpoint("models/", save_best_only=True)
Saves checkpoints as artifacts. Pair it with the metrics logger.
WandbEvalCallback
Base class for logging your own prediction tables each epoch.
WandbCallback()removed 0.27.1
The single Keras callback that did everything is gone — and the official Keras docs page still documents it. Use the two above.
wandb.integration.*
Also sb3, xgboost, lightgbm, ultralytics, sagemaker, openai_fine_tuning. All moved under this namespace in 0.17.0.

21Public API — querying backwandb.Api()

api = wandb.Api()
Read-only access to everything you have logged. Works outside a run.
runs = api.runs("entity/project")
Iterable of finished runs, newest first.
api.runs(p, {"config.lr": {"$lt": 0.01}})
MongoDB-style filters over config.*, summary_metrics.*, tags and state.
r.summary · r.config · r.name · r.state
The cheap fields. Enough to build a leaderboard DataFrame.
r.history(keys=["loss"]) · r.scan_history()
history() samples; scan_history() streams every row. Use scan when you need exact curves.
r.logged_artifacts() · r.used_artifacts()
Outputs and inputs — how you walk the lineage graph in code.
api.artifact("ent/proj/name:v2")
Fetch a specific version for serving or evaluation.
api.sweep(...).best_run()
Winner of a sweep, according to its declared metric.
WandbApiFailedError0.27.1
Public API calls route through wandb-core now and raise this instead of the old exception types. Update your retry handlers.

22Beyond experiment trackingthe rest of the platform

wandb-registry-{name}/{collection}
Registry: the promotion path from a project artifact to an org-wide, governed model.
pip install wandb-workspaces
Build reports and configure workspace views from Python instead of clicking.
import wandb_workspaces.reports.v2 as wr
Generate a shareable report at the end of a pipeline run.
pip install weave · weave.init("project")
Weave is the LLM product — tracing, evaluation, prompt versioning. A separate library from wandb.
wandb launch · wandb job
Package a run as a reproducible job and dispatch it to a queue or Kubernetes.
wandb.Api().create_registered_model(...)
Registry administration without leaving Python.

23What the tutorials still teach★all removed

wandb.log({...}) · wandb.summary · wandb.configgone
The big one. Only nine global functions remain: init login setup teardown sweep agent controller restore finish. Everything else is on the Run.
from wandb.keras import WandbCallback0.27.1
Removed. Use WandbMetricsLogger + WandbModelCheckpoint from wandb.integration.keras.
wandb.beta.workflows.log_model()0.24.0
→ run.log_artifact / use_artifact / link_artifact.
wandb.plots.*0.17.0
→ wandb.plot.*. One letter, and every old snippet breaks.
Run.plot_table()0.19.0
→ module-level wandb.plot_table().
run.get_url() · run.join()gone
→ run.url and run.finish().
wandb.integration.openai.autolog0.27.1
The OpenAI, Cohere and LangChain autologgers all moved to Weave.
wandb.init(anonymous=...)0.23.1
Anonymous mode deprecated.
wandb.require("core")unnecessary
The Go backend is the default since 0.18.0, and require("legacy-service") now raises.
wandb.integration.yolov80.27.1
Use the ultralytics integration instead.

24When something goes wrongthe usual suspects

# run stuck "running" forever
finish() was never called. Use a with block and it cannot happen.
# charts show half-empty alternating rows
Two log() calls per iteration. Combine them, or use commit=False.
# x-axis is "Step", not epochs
Log epoch as a metric and declare define_metric("*", step_metric="epoch").
# "config value changed" error
Pass allow_val_change=True, or stop reassigning the key.
# artifact not found right after logging
log_artifact() is async. Add .wait().
# sweep agent runs one job then exits
Missing count=, or the function raised. Check the agent's own stderr, not the run page.
# sweep runs ignore your hyperparameters
You read them from argparse instead of run.config.
# bounding boxes land in the corner
Coordinates are fractional unless you set "domain": "pixel".
# training slows down noticeably
watch() with log="all" and a low log_freq. Raise the frequency or unwatch.
# disk full on a shared filesystem
wandb artifact cache cleanup 1GB, and move WANDB_CACHE_DIR off the home volume.
wandb/debug.log · wandb/debug-internal.log
First place to look for anything else. The internal log has the network detail.

wandb cheat sheet

Setup & the Run object

Config & logging

Artifacts, sweeps & the wider platform

Four things worth seeing

Where a number lives

The step counter, three ways

What lineage actually records

Anatomy of a sweep

Worth memorizing