Class wandb.Run
A unit of computation logged by W&B. Typically, this is an ML experiment. Callwandb.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 withwandb.init():
Properties
The directory where a run’s files are saved.This refers to files saved with
run.save(), including automatically
created files for certain data types passed to run.log(). For the
directory containing all of a run’s data, see run.sync_dir.The name of the W&B entity associated with the run.Entity can be a username or the name of a team or organization.
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.
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.
Display name of the run.Display names are not guaranteed to be unique and may be descriptive.
By default, they are randomly generated.
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$.Path to the run.Run paths include entity, project, and run ID, in the format
entity/project/run_id.URL of the W&B project associated with the run, if there is one.Offline runs do not have a project URL.
URL of the sweep associated with the run, if there is one.Offline runs do not have a sweep URL.
The directory containing all of a run’s data.This can be passed to
wandb sync to upload or re-upload the run.Methods
method Run.alert()
Arguments
The time to wait (in seconds) before sending another alert with this title.
method Run.define_metric()
wandb.Run.log().
Arguments
The name of another metric to serve as the X-axis for this metric in automatically generated charts.
Automatically insert the last value of step_metric into
wandb.Run.log() if it is not provided explicitly. Defaults to True if step_metric is specified.Hide this metric from automatic plots.
Specify aggregate metrics added to summary. Supported aggregations include “min”, “max”, “mean”, “last”, “first”, “copy” and “none”. “none” prevents a summary from being generated. “copy” is deprecated and should not be used.
If false, then this call is merged with previous
define_metric calls for the same metric by using their values for any unspecified parameters. If true, then unspecified parameters overwrite values specified by previous calls.method Run.display()
Arguments
No description provided.
method Run.finish()
- 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.
Arguments
Integer indicating the run’s exit status. Use 0 for success, any other value marks the run as failed.
method Run.finish_artifact()
Arguments
A path to the contents of this artifact,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/pathYou can also pass an Artifact object created by callingwandb.Artifact.
An artifact name. May be prefixed with entity/project.
Valid names can be in the following forms:
- name:version
- name:alias
- digest This will default to the basename of the path prepended with the current run id if not specified.
method Run.link_artifact()
Arguments
The path of the collection. Path consists of the prefix “wandb-registry-” along with the registry name and the collection name
wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}.Add one or more aliases to the linked artifact. The “latest” alias is automatically applied to the most recent artifact you link.
Examples
method Run.link_model()
- 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.
Arguments
(str) A path to the contents of this model, can be in the
following forms:
/local/directory/local/directory/file.txts3://bucket/path
The name of the registered model that the model is to be linked to. A registered model is a collection of model versions linked to the model registry, typically representing a team’s specific ML Task. The entity that this registered model belongs to will be derived from the run.
The name of the model artifact that files in ‘path’ will be logged to. This will default to the basename of the path prepended with the current run id if not specified.
Aliases that will only be applied on this linked artifact inside the registered model. The alias “latest” will always be applied to the latest version of an artifact that is linked.
Raises
AssertionError: If registered_model_name is a path or if model artifact ‘name’ is of a type that does not contain the substring ‘model’.ValueError: If name has invalid special characters.
method Run.log()
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:
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”:
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.
wandb.Run.log() invocations to log to
the same step with the step and commit parameters.
The following are all equivalent:
Arguments
A
dict with str keys and values that are serializable Python objects including: int, float and string; any of the wandb.data_types; lists, tuples and NumPy arrays of serializable Python objects; other dicts of this structure.The step number to log. If
None, then an implicit auto-incrementing step is used. See the notes in the description.If true, finalize and upload the step. If false, then accumulate data for the step. See the notes in the description. If
step is None, then the default is commit=True; otherwise, the default is commit=False.Raises
wandb.Error: If called beforewandb.init().ValueError: If invalid data is passed.
Examples
For more and more detailed examples, see our guides to logging. Basic usagemethod Run.log_artifact()
Arguments
(str or Artifact) A path to the contents of this artifact,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/pathYou can also pass an Artifact object created by callingwandb.Artifact.
(str, optional) An artifact name. Valid names can be in the following forms:
- name:version
- name:alias
- digest This will default to the basename of the path prepended with the current run id if not specified.
method Run.log_code()
.py.
Arguments
(str, optional) The name of our code artifact. By default, we’ll name the artifact
source-$PROJECT_ID-$ENTRYPOINT_RELPATH. There may be scenarios where you want many runs to share the same artifact. Specifying name allows you to achieve that.A callable that accepts a file path and (optionally) root path and returns True when it should be included and False otherwise. This defaults to
lambda path, root: path.endswith(".py").A callable that accepts a file path and (optionally) root path and returns
True when it should be excluded and False otherwise. This defaults to a function that excludes all files within <root>/.wandb/ and <root>/wandb/ directories.Examples
Basic usagemethod Run.log_model()
Arguments
(str) A path to the contents of this model,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/path
A name to assign to the model artifact that the file contents will be added to. This will default to the basename of the path prepended with the current run id if not specified.
Raises
ValueError: If name has invalid special characters.
method Run.mark_preempting()
method Run.pin_config_keys()
Arguments
Config key names to pin, matching keys set via
run.config. These are exact key strings (dots and slashes are treated literally, not as path separators). Order is preserved and determines display order.method Run.restore()
Arguments
Optional path to a run to pull files from, i.e.
username/project_name/run_id if wandb.init has not been called, this is required.The directory to download the file to. Defaults to the current directory or the run directory if wandb.init was called.
Raises
CommError: If W&B can’t connect to the W&B backend.ValueError: If the file is not found or can’t find run_path.
method Run.save()
save is
called regardless of the policy. In particular, new files are not
picked up automatically.
glob_str is expanded using Python’s glob module: see
https://docs.python.org/3/library/glob.html for the exact syntax and
behavior. Notably, the characters *, ?, and [] are treated as
glob metacharacters, not literal characters, even if they appear in a
real filename (e.g. “myfile[1].txt”). If your file’s name contains
any of these characters and you want to match it literally rather
than as a pattern, either escape it yourself with glob.escape()
before calling save, or pass glob=False to disable pattern
expansion entirely and treat glob_str as a literal path.
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.
Arguments
One of
live, now, or end.- live: upload the file as it changes, overwriting the previous version
- now: upload the file once now
- end: upload file when the run ends
Whether to treat
glob_str as a glob pattern. Defaults to True for backward compatibility. Set to False to treat glob_str as a literal path, e.g. when its name contains glob metacharacters like [, ], *, or ? that you don’t want interpreted as a pattern.method Run.status()
method Run.unwatch()
Arguments
Optional list of pytorch models that have had watch called on them.
method Run.upsert_artifact()
Arguments
A path to the contents of this artifact,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/path
An artifact name. May be prefixed with “entity/project”. Defaults
to the basename of the path prepended with the current run ID
if not specified. Valid names can be in the following forms:
- name:version
- name:alias
- digest
method Run.use_artifact()
download or file on the returned object to get the contents locally.
Arguments
The name of the artifact to use. May be prefixed
with the name of the project the artifact was logged to
(“entity” or “entity/project”). If no
entity is specified in the name, the Run or API setting’s entity is used.
Valid names can be in the following forms
- name:version
- name:alias
Examples
method Run.use_model()
Arguments
A model artifact name. ‘name’ must match the name of an existing logged
model artifact. May be prefixed with
entity/project/. Valid names
can be in the following forms- model_artifact_name:version
- model_artifact_name:alias
Raises
AssertionError: If model artifact ‘name’ is of a type that does not contain the substring ‘model’.
method Run.watch()
Arguments
Specifies whether to log “gradients”, “parameters”, or “all”. Set to None to disable logging. (default=“gradients”).
Raises
ValueError: Ifwandb.init()has not been called or if any of the models are not instances oftorch.nn.Module.
method Run.write_logs()
write_logs to directly write text to the Logs tab instead of
relying on automatic stdout/stderr capture. Calls after the run has
finished are silently ignored.
Consider using the capture_loggers setting which integrates with
Python’s logging module.