Manage Runs

This guide provides a quick tour of run management functions.


This guide is a continuation of Guild AI Quick Start. Complete that guide before proceeding below.

A script to test runs

In the guild‑start directory, create a file named

msg = "Hello Guild!"

with open("message.txt", "w") as out:
    out.write(msg + "\n")

Verify that your project structure is:

  • guild-start
    • (created in Quick Start - not used in this guide)

Start runs

To start a run, use the run command.


guild run

Press Enter to accept the default message and run the operation. The script prints the greeting:

Hello Guild!

By default, Guild prompts you before starting the operation. You can bypass this prompt by including ‑y or ‑‑yes as a command line option:

guild run -y supports a single flag: msg, which it prints to the console. You can list supported flags for a script by specifying the ‑‑help‑op option to the run command:

guild run --help-op
Usage: guild run [OPTIONS] [FLAG]...

Use 'guild run --help' for a list of options.

  msg  (default is Hello Guild!)

We can run the script with a different value for msg:

guild run msg='Yo Guild!'
You are about to run
  msg: Yo Guild!
Continue? (Y/n)

Press Enter to continue. The script prints the alternate greeting:

Yo Guild!

While this is a very simple example — certainly not related to machine learning — it demonstrates that Guild runs your Python script unmodified and captures the result as a unique experiment. Later we see what Guild tracks for these operations.

Stop runs

By default, Guild lets a script run to completion, regardless of how long it takes to complete.

You can stop an operation early by typing Ctrl‑C in the command run console.

You can alternatively stop a run from a different console by running:

guild stop
Alternative to typing Ctrl‑C — run in a different command console

This stops all running operations. You can alternatively specify specific runs to stop. For more information, see the stop command.

List runs

List the latest 20 runs:

guild runs

List all runs by providing the ‑a or ‑‑all command line option:

guild runs --all

You can filter runs using a variety of options. For example, to show all runs with a status of completed, use the ‑C or ‑‑completed command line option:

guild runs --completed

Guild shows runs with a 1-based index, which may be in commands that accept runs as arguments.

For a list of filter options, see the runs command.

Show run info

If you want information about a run, use runs info:

guild runs info
id: be12ef24483d11e98c3ec85b764bbf34
status: completed
started: 2019-03-16 17:49:23
stopped: 2019-03-16 17:49:23
marked: no
run_dir: ~/.guild/runs/be12ef24483d11e98c3ec85b764bbf34
command: /usr/bin/python -um guild.op_main echo --msg "Yo Guild!"
exit_status: 0
  msg: Yo Guild!

By default, Guild shows information for the latest run. You can specify a different run as either an index or a run ID. For example, to show information for the second to last run:

guild runs info 2

You can request additional information by specifying various command line options:

  • Files associated with the run (‑‑files)
  • Run output (‑‑output)
  • Process environment (‑‑env)
  • Scalars (‑‑scalars)
  • Dependencies (‑‑deps)
  • Source code (‑‑source)

For more information, see the runs info command.

List run files

Show files associated with a run using the ls command:

guild ls

By default, Guild shows files associated with the latest run. You can specify a different run using a run index or run ID.

Show text files

The writes the value of the msg flag to a file named message.txt.

You can display the contents of a file using the cat command:

guild cat message.txt
Yo Guild!

To show the contents of message.txt for the previous run:

guild cat message.txt 2
Hello Guild!

Diff files

Guild supports diffing information across runs. For example, to diff message.txt across the last two runs, use:

guild diff --path message.txt

For more information, see the diff command.

Open run files

Use the open command to open a run directory in your system file browser:

guild open

By default, Guild opens the latest run directory.

You can open specific files using the ‑p or ‑‑path command line option:

guild open --path message.txt

You can browse the source code associated with a run by specifying the ‑‑source command line option:

guild open --source

Delete runs

Delete runs using runs delete or the alias runs rm.

By default, Guild deletes all runs. You can specify one or more runs to delete using these forms:

  • run index
  • run index range
  • run ID

Run index ranges are in the form START:STOP and will select all runs starts with index START up to and including the run with index STOP.

You can specify status filters such as ‑‑terminated, ‑‑error, ‑‑completed, etc.

For example, to delete the last run, use:

guild runs rm 1
You are about to delete the following runs:
  [c654363a]  2019-03-16 18:18:14  completed
  Delete 1 run(s)? (Y/n)

By default, Guild prompt before deleting runs. You can bypass this prompt by specifying the ‑y or ‑‑yes command line option.


Deleted runs can be restored later using runs restore. See below for details.


To delete all failed runs — i.e. runs with status error — use guild runs rm ‑‑error or the short version guild runs rm ‑E.

Restore deleted runs

Deleted runs can be restored using runs restore. By default, Guild restores all deleted runs. You can specify specific runs using indexes or run IDs. For example, to restore the last deleted run, use:

guild runs restore 1


To show deleted runs — i.e. runs that can be restored — use guild runs ‑‑deleted or the short version guild runs ‑d.

Label runs

Labels are short strings that you can associate with a run. Labels appear in run lists and in run comparisons by default. Labels can also be used to filter runs in any run-related command.

To label the latest run, use:

guild label get-started

Guild prompts before applying any labels, letting you see which runs are effected before any changes are made:

You are about to label the following runs with 'get-started':
  [f8d7c6e8]  2019-03-23 10:18:54  completed
  Continue? (Y/n)

Press Enter to apply the label.

Show runs with the get‑started label:

guild runs --label get-started

You can apply labels using a variety of selection options:

  • Run indexes and IDs
  • Operation
  • Run status
  • Labels
  • Marked status

For example, to label all of the runs, use:

guild label --operation get-started

Press Enter to apply the label.

You can clear labels using the ‑‑clear command line option:

guild label --clear 1:2

This command removes the label from the last two runs.

For more information, see the label command.

Marking runs

Runs may be marked to signify they have special meaning


In this guide you learned about basic run management, including how to:

  • Start and stop runs
  • List runs
  • Show run info
  • List and view run files
  • Delete and restore runs

Next steps

Train an image classifier implemented in Keras on the Fashion-MNIST data set.