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
wandb_config.Config
Config object associated with this run.
wandb_config.ConfigStatic
Static config object associated with this run.
str
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.bool
True if the run is disabled, False otherwise.
str
The name of the W&B entity associated with the run.Entity can be a username or the name of a team or organization.
str
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.
str
Identifier for this run.
str
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.
str | None
Display name of the run.Display names are not guaranteed to be unique and may be descriptive.
By default, they are randomly generated.
str | None
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$.bool
True if the run is offline, False otherwise.
str
Path to the run.Run paths include entity, project, and run ID, in the format
entity/project/run_id.str
Name of the W&B project associated with the run.
str | None
URL of the W&B project associated with the run, if there is one.Offline runs do not have a project URL.
bool
True if the run was resumed, False otherwise.
Settings
A frozen copy of run’s Settings object.
float
Unix timestamp (in seconds) of when the run started.
int
The W&B step of the next
log() call.Raises an error in mode=“shared” runs.str | None
Identifier for the sweep associated with the run, if there is one.
str | None
URL of the sweep associated with the run, if there is one.Offline runs do not have a sweep URL.
str
The directory containing all of a run’s data.This can be passed to
wandb sync to upload or re-upload the run.tuple | None
Tags associated with the run, if there are any.
str | None
The url for the W&B run, if there is one.Offline runs will not have a url.
Methods
method Run.alert()
Arguments
str
The title of the alert, must be less than 64 characters long.
str
The text body of the alert.
str | AlertLevel | None
The alert level to use, either:
INFO, WARN, or ERROR.int | float | timedelta | None
The time to wait (in seconds) before sending another alert with this title.
method Run.define_metric()
wandb.Run.log().
Arguments
str
The name of the metric to customize.
str | wandb_metric.Metric | None
The name of another metric to serve as the X-axis for this metric in automatically generated charts.
bool | None
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.
str | None
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.
bool | None
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
int
No description provided.
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
int | None
Integer indicating the run’s exit status. Use 0 for success, any other value marks the run as failed.
method Run.finish_artifact()
Arguments
Artifact | str
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 | None
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.
str | None
The type of artifact to log, examples include
dataset, modellist[str] | None
Aliases to apply to this artifact, defaults to
["latest"]str | None
Unique string that all distributed jobs share. If None, defaults to the run’s group name.
method Run.link_artifact()
Arguments
Artifact
The artifact object to link to the collection.
str
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}.list[str] | None
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
StrPath
(str) A path to the contents of this model, can be in the
following forms:
/local/directory/local/directory/file.txts3://bucket/path
str
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.
str | None
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.
list[str] | None
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
dict[str, Any]
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.int | None
The step number to log. If
None, then an implicit auto-incrementing step is used. See the notes in the description.bool | None
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
Artifact | StrPath
(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 | None
(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.
str | None
(str) The type of artifact to log, examples include
dataset, modellist[str] | None
(list, optional) Aliases to apply to this artifact, defaults to
["latest"]list[str] | None
(list, optional) Tags to apply to this artifact, if any.
method Run.log_code()
.py.
Arguments
str | None
The relative (to
os.getcwd()) or absolute path to recursively find code from.str | None
(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.Callable[[str, str], bool] | Callable[[str], bool]
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").Callable[[str, str], bool] | Callable[[str], bool]
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
StrPath
(str) A path to the contents of this model,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/path
str | None
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.
list[str] | None
Aliases to apply to the created model artifact, defaults to
["latest"]Raises
ValueError: If name has invalid special characters.
method Run.mark_preempting()
method Run.pin_config_keys()
Arguments
Sequence[str]
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
str
The name of the file.
str | None
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.bool
Whether to download the file even if it already exists locally
str | None
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
str | os.PathLike
A relative or absolute path or Unix glob.
str | os.PathLike | None
A path to use to infer a directory structure; see examples.
PolicyName
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
bool
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
torch.nn.Module | Sequence[torch.nn.Module] | None
Optional list of pytorch models that have had watch called on them.
method Run.upsert_artifact()
Arguments
Artifact | str
A path to the contents of this artifact,
can be in the following forms:
/local/directory/local/directory/file.txts3://bucket/path
str | None
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
str | None
The type of artifact to log. Common examples include
dataset, model.list[str] | None
Aliases to apply to this artifact, defaults to
["latest"].str | None
Unique string that all distributed jobs share. If None, defaults to the run’s group name.
method Run.use_artifact()
download or file on the returned object to get the contents locally.
Arguments
str | Artifact
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
str | None
The type of artifact to use.
list[str] | None
Aliases to apply to this artifact
str | None
This argument is deprecated and does nothing.
Examples
method Run.use_model()
Arguments
str
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
torch.nn.Module | Sequence[torch.nn.Module]
A single model or a sequence of models to be monitored.
torch.F | None
The loss function being optimized (optional).
Literal['gradients', 'parameters', 'all'] | None
Specifies whether to log “gradients”, “parameters”, or “all”. Set to None to disable logging. (default=“gradients”).
int
Frequency (in batches) to log gradients and parameters. (default=1000)
int | None
Index used when tracking multiple models with
wandb.watch. (default=None)bool
Whether to log the model’s computational graph. (default=False)
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.
Arguments
str
The text to write. A trailing newline is added if not present.