Skip to main content

Class wandb.Run

method Run.alert()

Create an alert with the given title and text.
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()

Customize metrics logged with 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.
bool | None
Hide this metric from automatic plots.
str | None
Specify aggregate metrics added to summary. Supported aggregations include “min”, “max”, “mean”, “last”, “first”, “best”, “copy” and “none”. “none” prevents a summary from being generated. “best” is used together with the goal parameter, “best” is deprecated and should not be used, use “min” or “max” instead. “copy” is deprecated and should not be used.
str | None
Specify how to interpret the “best” summary type. Supported options are “minimize” and “maximize”. “goal” is deprecated and should not be used, use “min” or “max” instead.
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.
Returns
An object that represents this call but can otherwise be discarded.

method Run.display()

Display this run in Jupyter.
Arguments
int
bool

method Run.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.
Arguments
int | None
Integer indicating the run’s exit status. Use 0 for success, any other value marks the run as failed.
bool | None
Deprecated. Configure logging verbosity using wandb.Settings(quiet=...).

method Run.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.
Arguments
Artifact | str
A path to the contents of this artifact, can be in the following forms:
  • /local/directory
  • /local/directory/file.txt
  • s3://bucket/path You can also pass an Artifact object created by calling wandb.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, 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.
Returns
An Artifact object. 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.
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.
Returns
The linked artifact. 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.
Arguments
StrPath
(str) A path to the contents of this model, can be in the following forms:
  • /local/directory
  • /local/directory/file.txt
  • s3://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.
Returns
The linked artifact if linking was successful, otherwise None.
Raises
If registered_model_name is a path or if model artifact ‘name’ is of a type that does not contain the substring ‘model’.
If name has invalid special characters.

method Run.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:
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”:
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.
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:
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
If called before wandb.init().
If invalid data is passed.
Examples
For more and more detailed examples, see our guides to logging. Basic usage
Incremental logging
Histogram
Image from NumPy
Image from PIL
Video from NumPy
Matplotlib plot
PR Curve
3D Object

method Run.log_artifact()

Declare an artifact as an output of a run.
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.txt
  • s3://bucket/path You can also pass an Artifact object created by calling wandb.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, model
list[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.
Returns
An Artifact object.

method 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.
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.
Returns
An Artifact object if code was logged
Examples
Basic usage
Advanced usage

method Run.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.
Arguments
StrPath
(str) A path to the contents of this model, can be in the following forms:
  • /local/directory
  • /local/directory/file.txt
  • s3://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"]
Returns
None
Raises
If name has invalid special characters.

method Run.mark_preempting()

Mark this run as preempting. Also tells the internal process to immediately report this to server.

method Run.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.
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()

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.
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.
Returns
None if it can’t find the file, otherwise a file object open for reading.
Raises
If W&B can’t connect to the W&B backend.
If the file is not found or can’t find run_path.

method Run.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. 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.
Returns
Paths to the symlinks created for the matched files. For historical reasons, this may return a boolean in legacy code. python import wandb run = wandb.init() run.save("these/are/myfiles/*") # => Saves files in a "these/are/myfiles/" folder in the run. run.save("these/are/myfiles/*", base_path="these") # => Saves files in an "are/myfiles/" folder in the run. run.save("/Users/username/Documents/run123/*.txt") # => Saves files in a "run123/" folder in the run. See note below. run.save("/Users/username/Documents/run123/*.txt", base_path="/Users") # => Saves files in a "username/Documents/run123/" folder in the run. run.save("files/*/saveme.txt") # => Saves each "saveme.txt" file in an appropriate subdirectory # of "files/". run.save("files/myfile[1].txt", glob=False) # => Saves the literal file "files/myfile[1].txt" without # interpreting "[1]" as a glob character class. # Explicitly finish the run since a context manager is not used. run.finish()

method Run.status()

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

method Run.unwatch()

Remove pytorch model topology, gradient and parameter hooks.
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()

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.
Arguments
Artifact | str
A path to the contents of this artifact, can be in the following forms:
  • /local/directory
  • /local/directory/file.txt
  • s3://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.
Returns
An Artifact object.

method Run.use_artifact()

Declare an artifact as an input to a run. Call 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.
Returns
An Artifact object.
Examples

method Run.use_model()

Download the files logged in a model artifact ‘name’.
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
Returns
path: Path to downloaded model artifact file(s).
Raises
If model artifact ‘name’ is of a type that does not contain the substring ‘model’.

method Run.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.
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
If wandb.init() has not been called or if any of the models are not instances of torch.nn.Module.

method Run.write_logs()

Write text to the run’s Logs tab. Use 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.