Run a model operation.
By default Guild will try to run
OPERATION for the default model
defined in the current project.
MODEL is specified, Guild will use it instead of the default
OPERATION may alternatively be a Python script. In this case any
current project is ignored and the script is run directly. Options
in the format
‑‑NAME=VAL can be passed to the script using
flags (see below).
[MODEL]:OPERATION may be omitted if
‑‑rerun is specified, in
which case the operation used in
RUN will be used.
FLAG values in the form
One or more batch files can be used to run multiple trials by
specifying the file path as
For example, to run trials specified in a CSV file named
guild run [MODEL:]OPERATION @trials.csv
NOTE: At this time you must specify the operation with batch files - batch files only contain flag values and cannot be used to run different operations for the same command.
Batch files may be formatted as CSV, JSON, or YAML. Format is determined by the file extension.
Each entry in the file is used as a set of flags for a trial run.
CSV files must have a header row containing the flag names. Each subsequent row is a corresponding list of flag values that will be used for a generated trial.
JSON and YAML files must contain a top-level list of flag-to-value maps.
‑‑print‑trials to preview the trials run for the specified
A list of flag values may be specified using the syntax
[VAL1[,VAL2]...]. Lists containing white space must be
quoted. When a list of values is provided, Guild will generate a
trial run for each value. When multiple flags have list values,
Guild generates the cartesian product of all possible flag
Flag lists may be used to perform grid search operations.
For example, the following generates four runs for operation
train and flags
guild run train learning‑rate[0.01,0.1] batch‑size=[10,100]
You can preview the trials generated from flag lists using
‑‑print‑trials. You can save the generated trials to a batch
‑‑save‑trials. For more information, see PREVIEWING
AND SAVING TRIALS below.
‑‑optimizer is specified, flag lists may take on different
meaning depending on the type of optimizer. For example, the
random optimizer will randomly select values from a flag list,
rather than generate trials for each value. See OPTIMIZERS for
A run may be optimized using
‑‑optimizer. An optimizer runs up
‑‑max‑trials runs using flag values and flag configuration.
For details on available optimizers and their behavior, refer to https://guild.ai/docs/optimizers.
When using flag lists or optimizers, which generate trials, you
can limit the number of trials with
‑‑max‑trials. By default,
Guild limits the number of generated trials to 20.
Guild limits trials by randomly sampling the maximum number from
the total list of generated files. You can specify the seed used
for the random sample with
‑‑random‑seed. The random seed is
guaranteed to generate consistent results when used on the same
version of Python. When used across different versions of Python,
the results may be inconsistent.
Previewing and saving trials
When flag lists (used for grid search) or an optimizer is used,
you can preview the generated trials using
can save the generated trials as a CSV batch file using
‑‑rerun is specified, the operation and flags used in
will be applied to the new operation. You may add or redefine
flags in the new operation. You may also use an alternative
operation, in which case only the flag values from
RUN will be
RUN must be a run ID or unique run ID prefix or the
0, which indicates the latest run.
‑‑restart is specified, the specified
RUN is restarted
in-place using its operation and flags. Unlike rerun, restart does
not create a new run, but instead reuses the run directory of
RUN. Like a rerun, a restart may specify a different operation
and additional flags and may use
0 for the value of
restart the latest run.
‑‑run‑dir may not be used with
‑‑restart may not both be used.
Alternate run directory
To run an operation outside of Guild's run management facility,
‑‑stage to specify an alternative run
directory. These options are useful when developing or debugging
an operation. Use
‑‑stage to prepare a run directory for an
operation without running the operation itself. This is useful
when you want to verify dependency resolution and pre-processing
or manually run an operation in a prepared directory.
NOTE: Runs started with
‑‑run‑dir are not visible to Guild
and will not appear in run listings.
Controlling visible GPU devices
By default, operations have access to all available GPU
devices. To limit the GPU devices available to a run, use
For example, to limit visible GPU devices to
guild run ‑‑gpus 0,1 ...
To disable all available GPUs, use
‑‑no‑gpus are used to construct the
CUDA_VISIBLE_DEVICES environment variable used for the run
CUDA_VISIBLE_DEVICES is set, using either of these
options will cause it to be redefined for the run.
‑‑optimizer to run the operation multiple times in attempt
to optimize a result. Use
‑‑maximize to indicate
what should be optimized. Use
‑‑max‑runs to indicate the maximum
number of runs the optimizer should generate.
|-l, --label LABEL||
Set a label for the run.
|-d, --run-dir DIR||
Use alternative run directory DIR. Cannot be used with --stage.
Stage an operation in DIR but do not run. Cannot be used with --run-dir.
Use the operation and flags from RUN. Flags may be added or redefined in this operation. Cannot be used with --restart.
Restart RUN in-place without creating a new run. Cannot be used with --rerun or --run-dir.
A comma separated list of plugin names to disable. Use 'all' to disable all plugins.
Limit availabe GPUs to DEVICES, a comma separated list of device IDs. By default all GPUs are available. Cannot beused with --no-gpus.
Disable GPUs for run. Cannot be used with --gpu.
|-o, --optimizer ALGORITHM||
Optimize the run using the specified algorithm. See Optimizing Runs for more information.
Optimize the run using the default optimizer.
|-N, --minimize COLUMN||
Column to minimize when running with an optimizer. See help for compare command for details specifying a column. May not be used with --maximize.
|-X, --maximize COLUMN||
Column to maximize when running with an optimizer. See help for compare command for details specifying a column. May not be used with --minimize.
|-Fo, --opt-flag FLAG=VAL||
Flag for OPTIMIZER. May be used multiple times.
|-m, --max-trials N||
Maximum number of trials to run in batch operations. Default is optimizer specific. If optimizer is not specified, default is 20.
Random seed used when sampling trials or flag values.
For batch operations, initialize trials without running them.
|-r, --remote REMOTE||
Run the operation remotely.
Do not prompt before running operation.
Accept all flag assignments, even for undefined or invalid flags.
Stop operation after N minutes.
Run only if there is not an available matching run. A matching run is of the same operation with the same flag values that is not stopped due to an error.
Run operation in background.
Run operation in background, writing the background process ID to PIDFILE.
Don't wait for a remote operation to complete. Ignored if run is local.
Saves generated trials to a CSV batch file. See BATCH FILES for more information.
Enter the Python debugger at the operation entry point.
Do not show output.
Show operation command and exit.
Show operation environment and exit.
Show generated trials and exit.
Show model help and exit.
Show operation help and exit.
Test output scalars on output.
|--help||Show command help and exit.|