Run

settings: 'Settings',
config: 'dict[str, Any] | None' = None,
sweep_config: 'dict[str, Any] | None' = None,
launch_config: 'dict[str, Any] | None' = None

Description

A unit of computation logged by W&B. Typically, this is an ML experiment.

Call wandb.init() to create a new run. wandb.init() starts a new run and returns a wandb.Run object. Each run is associated with a unique ID (run ID). W&B recommends using a context (with statement) manager to automatically finish the run.

For distributed training experiments, you can either track each process separately using one run per process or track all processes to a single run. See Log distributed training experiments for more information.

You can log data to a run with wandb.Run.log(). Anything you log using wandb.Run.log() is sent to that run. See Create an experiment or wandb.init API reference page or more information.

There is a another Run object in the wandb.apis.public namespace. Use this object is to interact with runs that have already been created.

Attributes: summary: (Summary) A summary of the run, which is a dictionary-like object. For more information, see Log summary metrics.

Examples:

Create a run with wandb.init():

import wandb

# Start a new run and log some data
# Use context manager (`with` statement) to automatically finish the run
with wandb.init(entity="entity", project="project") as run:
    run.log({"accuracy": acc, "loss": loss})

Args:

• settings:
• config:
• sweep_config:
• launch_config:

Properties:

settings

A frozen copy of run’s Settings object.

dir

The directory where files associated with the run are saved.

config

Config object associated with this run.

config_static

Static config object associated with this run.

name

Display name of the run.

Display names are not guaranteed to be unique and may be descriptive. By default, they are randomly generated.

notes

Notes associated with the run, if there are any.

Notes can be a multiline string and can also use markdown and latex equations inside $$, like $x + 3$.

tags

Tags associated with the run, if there are any.

id

Identifier for this run.

sweep_id

Identifier for the sweep associated with the run, if there is one.

path

Path to the run.

Run paths include entity, project, and run ID, in the format entity/project/run_id.

start_time

Unix timestamp (in seconds) of when the run started.

resumed

True if the run was resumed, False otherwise.

offline

True if the run is offline, False otherwise.

disabled

True if the run is disabled, False otherwise.

group

Returns the name of the group associated with this run.

Grouping runs together allows related experiments to be organized and visualized collectively in the W&B UI. This is especially useful for scenarios such as distributed training or cross-validation, where multiple runs should be viewed and managed as a unified experiment.

In shared mode, where all processes share the same run object, setting a group is usually unnecessary, since there is only one run and no grouping is required.

job_type

Name of the job type associated with the run.

View a run’s job type in the run’s Overview page in the W&B App.

You can use this to categorize runs by their job type, such as “training”, “evaluation”, or “inference”. This is useful for organizing and filtering runs in the W&B UI, especially when you have multiple runs with different job types in the same project. For more information, see Organize runs.

project

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

project_url

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

Offline runs do not have a project URL.

sweep_url

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

Offline runs do not have a sweep URL.

url

The url for the W&B run, if there is one.

Offline runs will not have a url.

entity

The name of the W&B entity associated with the run.

Entity can be a username or the name of a team or organization.

Methods:

alert

Create an alert with the given title and text.

define_metric

Customize metrics logged with wandb.Run.log().

display

Display this run in Jupyter.

finish

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).
• Killed: Run was forcibly stopped before it could finish.

finish_artifact

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

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

link_artifact

Link the artifact to a collection.

The term “link” refers to pointers that connect where W&B stores the artifact and where the artifact is accessible in the registry. W&B does not duplicate artifacts when you link an artifact to a collection.

View linked artifacts in the Registry UI for the specified collection.

link_model

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

Linked model versions are visible in the UI for the specified registered model.

This method will:

• 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.

log

Upload run data.

Use log to log data from runs, such as scalars, images, video, histograms, plots, and tables. See Log objects and media for code snippets, best practices, and more.

Basic usage:

import wandb

with wandb.init() as run:
    run.log({"train-loss": 0.5, "accuracy": 0.9})

The previous code snippet saves the loss and accuracy to the run’s history and updates the summary values for these metrics.

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

Logged values don’t have to be scalars. You can log any W&B supported Data Type such as images, audio, video, and more. For example, you can use wandb.Table to log structured data. See Log tables, visualize and query data tutorial for more details.

W&B 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”:

with wandb.init() as run:
    # Log metrics in the "train" section.
    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”.

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.

By default, each call to log creates a new “step”. The step must always increase, and it is not possible to log to a previous step. You can use any metric as the X axis in charts. See Custom log axes for more details.

In many cases, it is better to treat the W&B step like you’d treat a timestamp rather than a training step.

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

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

with wandb.init() as run:
    # 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, commit=True)

log_artifact

Declare an artifact as an output of a run.

log_code

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.

log_model

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

The name of model artifact can only contain alphanumeric characters, underscores, and hyphens.

mark_preempting

Mark this run as preempting.

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

pin_config_keys

Pin config keys to display in the References section on Run Overview.

Pinned keys appear prominently above Notes on the Run Overview page. String values are rendered as markdown; non-strings are rendered as plain text. Calling this again replaces the previously pinned list.

restore

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

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.

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

Files are automatically deduplicated: calling save() multiple times on the same file without modifications will not re-upload it.

status

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

unwatch

Remove pytorch model topology, gradient and parameter hooks.

upsert_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

Declare an artifact as an input to a run.

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

use_model

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

watch

Hook into given PyTorch model to monitor gradients and the model’s computational graph.

This function can track parameters, gradients, or both during training.