Get Started with Guild AI

Install Guild AI

If you’re familiar with installing Python packages using pip, simply install the guildai package.

pip install guildai

Alternatively, to install to the user install directory, run:

pip install guildai --user

For detailed installation instructions, see Install Guild AI.

When Guild is installed, check the environment:

guild check

For help troubleshooting, see Get Help with Guid AI.

Get Command Help

Guild’s primary interface is the command line. Commands are run using the format guild COMMAND. Use the --help option to show information for a command.

Show all Guild commands:

guild --help

See Guild AI Commands for a complete reference.

Create a Sample Training Script

In the steps below, you create a sample training script and run it to generate experiments.

Create a new project directory:

mkdir guild-start

Note You can name this directory anything you want. The examples that follow use guild-start to denote the project directory for this guide.

Change to the project directory:

cd guild-start

In the project directory, create a file named that contains this Python code:

import numpy as np

# Hyperparameters
x = 0.1
noise = 0.1

# Simulated training loss
loss = (np.sin(5 * x) * (1 - np.tanh(x ** 2)) + np.random.randn() * noise)

print("loss: %f" % loss)

Sample script — adapted from Bayesian optimization with skopt

This script simulates a loss function. It accepts hyperparameters x and noise and prints the resulting loss.

The project directory should look like this:


Run the Script

Use Guild to run

guild run
You are about to run
  noise: 0.1
  x: 0.1
Continue? (Y/n)

Press Enter to start the operation.

Guild runs, which prints a simulated loss.

When Guild runs a script, it generates a new experiment, or run. Each run tracks experiment details including results.

Highlight Guild lets you track experiments without changing your scripts. This saves time and keeps your source independent of an experiment tracking system.

Guild inspects and detects two hyperparameters: noise and x. Guild refers to these variables as flags. By default, Guild treats global constants in Python scripts as flags. This behavior can be controlled through explicit configuration, which you learn about later.

View Results

Start the Guild View application:

guild view

Guild starts the application, and opens a tab in your browser. Guild View runs in the background in the command terminal.

Use Guild View to browse runs, view run details including metadata, files, and log output. You can compare run results and run artifacts in TensorBoard.

Guild View — a web based application for viewing runs and comparing results

Return to the command terminal and press Ctrl-C to stop Guild View.

View Results from the Terminal

When working in a command line environment, it’s convenient to use the terminal to view run results.

From your terminal, use guild runs to list the current runs:

guild runs
[1:68f4da74]  2020-01-14 08:42:54  completed  noise=0.1 x=0.1

Guild lists runs, showing the run ID, operation name, start time, status, and label. As you generate more runs, they appear in this list.

Information about each run is saved in a run directory, including metadata, flag inputs, and results.

Use guild runs info to show information about a run:

guild runs info
id: 68f4da7428bd49b5a8946863909f84dc
from: ~/Projects/guild-start
status: completed
started: 2020-01-14 08:42:54
stopped: 2020-01-14 08:42:54
marked: no
label: noise=0.1 x=0.1
sourcecode_digest: 9d846ffb2022c9540d7b01a160617881
run_dir: ~/.guild/runs/68f4da7428bd49b5a8946863909f84dc
command: /usr/bin/python -um guild.op_main train --noise 0.1 --x 0.1
exit_status: 0
  noise: 0.1
  x: 0.1
  loss: 0.388010 (step 0)

By default, Guild shows information for the latest run.

Highlight Guild captures detailed information for each run so you have a complete record of each result. This information is useful for making informed decisions and tracking changes to your model.

Project Source Code

Guild saves project source code for each run.

To list source code, include the --sourcecode option with guild ls:

guild ls --sourcecode

Highlight Guild snapshots the source code at the time the operation is run so you have an accurate record of what executed. You don’t have to commit your code to a repository before starting a run. You can freely modify your project source while operations are running.

Use the --sourcecode option with guild cat to view source code associated with a run :

guild cat --sourcecode --path
import numpy as np

# Hyperparameters
x = 0.1
noise = 0.1

# Simulated training loss
loss = (np.sin(5 * x) * (1 - np.tanh(x ** 2)) + np.random.randn() * noise)

print("loss: %f" % loss)

You can also open source code files in your system editor with guild open:

guild open --sourcecode --path

Guild opens the copy used for the run with the default system program for py files.

View a run file in a system program with guild open


In this section, you use Guild AI to capture experiments for a sample training script.


  • Guild lets you track experiments without changing your code.
  • Guild is easy to install and use. It doesn’t require databases or external systems.
  • Guild captures details about your work that you use to optimize performance, catch mistakes, and resolve problems.

In the next section, you use Guild’s built-in hyperparameter tuning support to find values for x that minimize loss for the sample training script.

Next: Optimize a Model