Run

A unit of computation logged by wandb. Typically, this is an ML experiment.

Create a run with wandb.init():

import wandb

run = wandb.init()

There is only ever at most one active wandb.Run in any process, and it is accessible as wandb.run:

import wandb

assert wandb.run is None

wandb.init()

assert wandb.run is not None

anything you log with wandb.log will be sent to that run.

If you want to start more runs in the same script or notebook, you’ll need to finish the run that is in-flight. Runs can be finished with wandb.finish or by using them in a with block:

import wandb

wandb.init()
wandb.finish()

assert wandb.run is None

with wandb.init() as run:
    pass  # log data here

assert wandb.run is None

See the documentation for wandb.init for more on creating runs, or check out our guide to wandb.init.

In distributed training, you can either create a single run in the rank 0 process and then log information only from that process, or you can create a run in each process, logging from each separately, and group the results together with the group argument to wandb.init. For more details on distributed training with W&B, check out our guide.

Currently, there is a parallel Run object in the wandb.Api. Eventually these two objects will be merged.

Methods

alert

View source

alert(
    title: str,
    text: str,
    level: (str | AlertLevel | None) = None,
    wait_duration: (int | float | timedelta | None) = None
) -> None

Launch an alert with the given title and text.

define_metric

View source

define_metric(
    name: str,
    step_metric: (str | wandb_metric.Metric | None) = None,
    step_sync: (bool | None) = None,
    hidden: (bool | None) = None,
    summary: (str | None) = None,
    goal: (str | None) = None,
    overwrite: (bool | None) = None
) -> wandb_metric.Metric

Customize metrics logged with wandb.log().

display

View source

display(
    height: int = 420,
    hidden: bool = (False)
) -> bool

Display this run in jupyter.

finish

View source

finish(
    exit_code: (int | None) = None,
    quiet: (bool | None) = None
) -> None

Finish a run and upload any remaining data.

Marks the completion of a W&B run and ensures all data is synced to the server. The run’s final state is determined by its exit conditions and sync status.

Run States:

• Running: Active run that is logging data and/or sending heartbeats.
• Crashed: Run that stopped sending heartbeats unexpectedly.
• Finished: Run completed successfully (exit_code=0) with all data synced.
• Failed: Run completed with errors (exit_code!=0).

finish_artifact

View source

finish_artifact(
    artifact_or_path: (Artifact | str),
    name: (str | None) = None,
    type: (str | None) = None,
    aliases: (list[str] | None) = None,
    distributed_id: (str | None) = None
) -> Artifact

Finishes a non-finalized artifact as output of a run.

Subsequent “upserts” with the same distributed ID will result in a new version.

get_project_url

View source

get_project_url() -> (str | None)

URL of the W&B project associated with the run, if there is one.

Offline runs do not have a project URL.

Note: this method is deprecated and will be removed in a future release. Please use run.project_url instead.

get_sweep_url

View source

get_sweep_url() -> (str | None)

The URL of the sweep associated with the run, if there is one.

Offline runs do not have a sweep URL.

Note: this method is deprecated and will be removed in a future release. Please use run.sweep_url instead.

get_url

View source

get_url() -> (str | None)

URL of the W&B run, if there is one.

Offline runs do not have a URL.

Note: this method is deprecated and will be removed in a future release. Please use run.url instead.

link_artifact

View source

link_artifact(
    artifact: Artifact,
    target_path: str,
    aliases: (list[str] | None) = None
) -> (Artifact | None)

Link the given artifact to a portfolio (a promoted collection of artifacts).

The linked artifact will be visible in the UI for the specified portfolio.

link_model

View source

link_model(
    path: StrPath,
    registered_model_name: str,
    name: (str | None) = None,
    aliases: (list[str] | None) = None
) -> (Artifact | None)

Log a model artifact version and link it to a registered model in the model registry.

The linked model version will be visible in the UI for the specified registered model.

Steps:

• Check if ’name’ model artifact has been logged. If so, use the artifact version that matches the files located at ‘path’ or log a new version. Otherwise log files under ‘path’ as a new model artifact, ’name’ of type ‘model’.
• Check if registered model with name ‘registered_model_name’ exists in the ‘model-registry’ project. If not, create a new registered model with name ‘registered_model_name’.
• Link version of model artifact ’name’ to registered model, ‘registered_model_name’.
• Attach aliases from ‘aliases’ list to the newly linked model artifact version.

Examples:

run.link_model(
    path="/local/directory",
    registered_model_name="my_reg_model",
    name="my_model_artifact",
    aliases=["production"],
)

Invalid usage

run.link_model(
    path="/local/directory",
    registered_model_name="my_entity/my_project/my_reg_model",
    name="my_model_artifact",
    aliases=["production"],
)

run.link_model(
    path="/local/directory",
    registered_model_name="my_reg_model",
    name="my_entity/my_project/my_model_artifact",
    aliases=["production"],
)

log

View source

log(
    data: dict[str, Any],
    step: (int | None) = None,
    commit: (bool | None) = None
) -> None

Upload run data.

Use log to log data from runs, such as scalars, images, video, histograms, plots, and tables.

See our guides to logging for live examples, code snippets, best practices, and more.

The most basic usage is run.log({"train-loss": 0.5, "accuracy": 0.9}). This will save the loss and accuracy to the run’s history and update the summary values for these metrics.

Visualize logged data in the workspace at wandb.ai, or locally on a self-hosted instance of the W&B app, or export data to visualize and explore locally, e.g. in Jupyter notebooks, with our API.

Logged values don’t have to be scalars. Logging any wandb object is supported. For example run.log({"example": wandb.Image("myimage.jpg")}) will log an example image which will be displayed nicely in the W&B UI. See the reference documentation for all of the different supported types or check out our guides to logging for examples, from 3D molecular structures and segmentation masks to PR curves and histograms. You can use wandb.Table to log structured data. See our guide to logging tables for details.

The W&B UI organizes metrics with a forward slash (/) in their name into sections named using the text before the final slash. For example, the following results in two sections named “train” and “validate”:

run.log(
    {
        "train/accuracy": 0.9,
        "train/loss": 30,
        "validate/accuracy": 0.8,
        "validate/loss": 20,
    }
)

Only one level of nesting is supported; run.log({"a/b/c": 1}) produces a section named “a/b”.

run.log is not intended to be called more than a few times per second. For optimal performance, limit your logging to once every N iterations, or collect data over multiple iterations and log it in a single step.

The W&B step

With basic usage, each call to log creates a new “step”. The step must always increase, and it is not possible to log to a previous step.

Note that you can use any metric as the X axis in charts. In many cases, it is better to treat the W&B step like you’d treat a timestamp rather than a training step.

# Example: log an "epoch" metric for use as an X axis.
run.log({"epoch": 40, "train-loss": 0.5})

See also define_metric.

It is possible to use multiple log invocations to log to the same step with the step and commit parameters. The following are all equivalent:

# Normal usage:
run.log({"train-loss": 0.5, "accuracy": 0.8})
run.log({"train-loss": 0.4, "accuracy": 0.9})

# Implicit step without auto-incrementing:
run.log({"train-loss": 0.5}, commit=False)
run.log({"accuracy": 0.8})
run.log({"train-loss": 0.4}, commit=False)
run.log({"accuracy": 0.9})

# Explicit step:
run.log({"train-loss": 0.5}, step=current_step)
run.log({"accuracy": 0.8}, step=current_step)
current_step += 1
run.log({"train-loss": 0.4}, step=current_step)
run.log({"accuracy": 0.9}, step=current_step)

Examples:

For more and more detailed examples, see our guides to logging.

Basic usage

import wandb

run = wandb.init()
run.log({"accuracy": 0.9, "epoch": 5})

Incremental logging

import wandb

run = wandb.init()
run.log({"loss": 0.2}, commit=False)
# Somewhere else when I'm ready to report this step:
run.log({"accuracy": 0.8})

Histogram

import numpy as np
import wandb

# sample gradients at random from normal distribution
gradients = np.random.randn(100, 100)
run = wandb.init()
run.log({"gradients": wandb.Histogram(gradients)})

Image from numpy

import numpy as np
import wandb

run = wandb.init()
examples = []
for i in range(3):
    pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
    image = wandb.Image(pixels, caption=f"random field {i}")
    examples.append(image)
run.log({"examples": examples})

Image from PIL

import numpy as np
from PIL import Image as PILImage
import wandb

run = wandb.init()
examples = []
for i in range(3):
    pixels = np.random.randint(
        low=0,
        high=256,
        size=(100, 100, 3),
        dtype=np.uint8,
    )
    pil_image = PILImage.fromarray(pixels, mode="RGB")
    image = wandb.Image(pil_image, caption=f"random field {i}")
    examples.append(image)
run.log({"examples": examples})

Video from numpy

import numpy as np
import wandb

run = wandb.init()
# axes are (time, channel, height, width)
frames = np.random.randint(
    low=0,
    high=256,
    size=(10, 3, 100, 100),
    dtype=np.uint8,
)
run.log({"video": wandb.Video(frames, fps=4)})

Matplotlib Plot

from matplotlib import pyplot as plt
import numpy as np
import wandb

run = wandb.init()
fig, ax = plt.subplots()
x = np.linspace(0, 10)
y = x * x
ax.plot(x, y)  # plot y = x^2
run.log({"chart": fig})

PR Curve

import wandb

run = wandb.init()
run.log({"pr": wandb.plot.pr_curve(y_test, y_probas, labels)})

3D Object

import wandb

run = wandb.init()
run.log(
    {
        "generated_samples": [
            wandb.Object3D(open("sample.obj")),
            wandb.Object3D(open("sample.gltf")),
            wandb.Object3D(open("sample.glb")),
        ]
    }
)

log_artifact

View source

log_artifact(
    artifact_or_path: (Artifact | StrPath),
    name: (str | None) = None,
    type: (str | None) = None,
    aliases: (list[str] | None) = None,
    tags: (list[str] | None) = None
) -> Artifact

Declare an artifact as an output of a run.

log_code

View source

log_code(
    root: (str | None) = ".",
    name: (str | None) = None,
    include_fn: (Callable[[str, str], bool] | Callable[[str], bool]) = _is_py_requirements_or_dockerfile,
    exclude_fn: (Callable[[str, str], bool] | Callable[[str], bool]) = filenames.exclude_wandb_fn
) -> (Artifact | None)

Save the current state of your code to a W&B Artifact.

By default, it walks the current directory and logs all files that end with .py.

Examples:

Basic usage

run.log_code()

Advanced usage

run.log_code(
    "../",
    include_fn=lambda path: path.endswith(".py") or path.endswith(".ipynb"),
    exclude_fn=lambda path, root: os.path.relpath(path, root).startswith(
        "cache/"
    ),
)

log_model

View source

log_model(
    path: StrPath,
    name: (str | None) = None,
    aliases: (list[str] | None) = None
) -> None

Logs a model artifact containing the contents inside the ‘path’ to a run and marks it as an output to this run.

Examples:

run.log_model(
    path="/local/directory",
    name="my_model_artifact",
    aliases=["production"],
)

Invalid usage

run.log_model(
    path="/local/directory",
    name="my_entity/my_project/my_model_artifact",
    aliases=["production"],
)

mark_preempting

View source

mark_preempting() -> None

Mark this run as preempting.

Also tells the internal process to immediately report this to server.

project_name

View source

project_name() -> str

Name of the W&B project associated with the run.

Note: this method is deprecated and will be removed in a future release. Please use run.project instead.

restore

View source

restore(
    name: str,
    run_path: (str | None) = None,
    replace: bool = (False),
    root: (str | None) = None
) -> (None | TextIO)

Download the specified file from cloud storage.

File is placed into the current directory or run directory. By default, will only download the file if it doesn’t already exist.

save

View source

save(
    glob_str: (str | os.PathLike),
    base_path: (str | os.PathLike | None) = None,
    policy: PolicyName = "live"
) -> (bool | list[str])

Sync one or more files to W&B.

Relative paths are relative to the current working directory.

A Unix glob, such as “myfiles/*”, is expanded at the time save is called regardless of the policy. In particular, new files are not picked up automatically.

A base_path may be provided to control the directory structure of uploaded files. It should be a prefix of glob_str, and the directory structure beneath it is preserved. It’s best understood through examples:

wandb.save("these/are/myfiles/*")
# => Saves files in a "these/are/myfiles/" folder in the run.

wandb.save("these/are/myfiles/*", base_path="these")
# => Saves files in an "are/myfiles/" folder in the run.

wandb.save("/User/username/Documents/run123/*.txt")
# => Saves files in a "run123/" folder in the run. See note below.

wandb.save("/User/username/Documents/run123/*.txt", base_path="/User")
# => Saves files in a "username/Documents/run123/" folder in the run.

wandb.save("files/*/saveme.txt")
# => Saves each "saveme.txt" file in an appropriate subdirectory
#    of "files/".

Note: when given an absolute path or glob and no base_path, one directory level is preserved as in the example above.

status

View source

status() -> RunStatus

Get sync info from the internal backend, about the current run’s sync status.

to_html

View source

to_html(
    height: int = 420,
    hidden: bool = (False)
) -> str

Generate HTML containing an iframe displaying the current run.

unwatch

View source

unwatch(
    models: (torch.nn.Module | Sequence[torch.nn.Module] | None) = None
) -> None

Remove pytorch model topology, gradient and parameter hooks.

upsert_artifact

View source

upsert_artifact(
    artifact_or_path: (Artifact | str),
    name: (str | None) = None,
    type: (str | None) = None,
    aliases: (list[str] | None) = None,
    distributed_id: (str | None) = None
) -> Artifact

Declare (or append to) a non-finalized artifact as output of a run.

Note that you must call run.finish_artifact() to finalize the artifact. This is useful when distributed jobs need to all contribute to the same artifact.

use_artifact

View source

use_artifact(
    artifact_or_name: (str | Artifact),
    type: (str | None) = None,
    aliases: (list[str] | None) = None,
    use_as: (str | None) = None
) -> Artifact

Declare an artifact as an input to a run.

Call download or file on the returned object to get the contents locally.

use_model

View source

use_model(
    name: str
) -> FilePathStr

Download the files logged in a model artifact ’name’.

Examples:

run.use_model(
    name="my_model_artifact:latest",
)

run.use_model(
    name="my_project/my_model_artifact:v0",
)

run.use_model(
    name="my_entity/my_project/my_model_artifact:<digest>",
)

Invalid usage

run.use_model(
    name="my_entity/my_project/my_model_artifact",
)

watch

View source

watch(
    models: (torch.nn.Module | Sequence[torch.nn.Module]),
    criterion: (torch.F | None) = None,
    log: (Literal['gradients', 'parameters', 'all'] | None) = "gradients",
    log_freq: int = 1000,
    idx: (int | None) = None,
    log_graph: bool = (False)
) -> None

Hooks into the given PyTorch model(s) to monitor gradients and the model’s computational graph.

This function can track parameters, gradients, or both during training. It should be extended to support arbitrary machine learning models in the future.

__enter__

View source

__enter__() -> Run

__exit__

View source

__exit__(
    exc_type: type[BaseException],
    exc_val: BaseException,
    exc_tb: TracebackType
) -> bool