Environments

[guildai]

Overview

A Guild environment is a system runtime used to manage runs. All Guild commands are executed in the context of a Guild environment.

View information about the current environment using guild check.

The guild_home attribute in check output indicates the location of the Guild environment. By default the Guild environment is ~/.guild where ~ is the active user home directory. For more information, see Guild Home below.

Virtual Environments

By default, Guild environments correspond to activated virtual environments. Use virtual environments created using conda or virtualenv to isolate your work, including Guild runs.

Virtual environment let you run Python operations using a specific Python runtime along with a controlled set of installed libraries. When you activate a virtual environment, Guild operations run within this isolated context.

By default, runs are stored within the virtual environment. This lets you isolate your project work per environment. You can change this behavior so that runs are stored in a different location by changing the location of Guild home.

Important Take care when deleting virtual environments as they may contain Guild runs. Look for .guild/runs within the virtual environment directory to verify that you aren’t accidentally deleting runs.

Guild Home

Guild home is a directory that contains Guild-maintained files. These include:

• Runs
• Cached downloaded resources
• Cached run output scalars
• Remote state
• Deleted runs
• Interprocess locks

Guild Home is laid out as follows:

Guild Home Directory	default is ~/.guild or <venv>/.guild within a virtual env
cache	Guild-maintained caches
import-flags	cached flags imported from scripts
resources	cached resources
runs	indexed run scalars
locks	interprocess resource locks
remotes	remote state
runs	indexed run attributes and scalars
trash	deleted objects
runs	deleted runs

Tip Use guild check to show the current Guild home. This is the value shown for guild_home in the output.

Set Guild Home

By default, Guild resolves Guild home by first looking in the activated virtual environment. If an environment isn’t activated, Guild uses .guild in the current user’s home directory.

You can specify a different location for Guild home using one of two methods:

• Set GUILD_HOME environment variable
• Use -H when running a Guild command

To set GUILD_HOME for all Guild commands in a command shell, run:

export GUILD_HOME=<path>

To set Guild home for one command, use one of these methods:

GUILD_HOME=<path> guild <command> ...

or:

guild -H <path> <command> ...

Note When using -H, the option must be specified before <command>.

For help setting environment variables on Windows, see Help with Windows.

Create a Guild Environment

New environments may be created using the following methods:

• Use guild init
• Use one of the standard Python tools: virtualenv, venv, or conda
• Create a new directory and set it as Guild home

guild init command uses virtualenv to create a new virtual environment. When running init, Guild performs additional steps to streamline the process of creating a virtualized Guild environment for a project:

• Uses a Python dependency specification to select an appropriate Python version when creating the virtual environment
• Runs pip install -r requirements.txt if requirements.txt is defined for a project

Activate Virtual Environments

You must activate a virtual environment before using it. Activate a virtual environment using the applicable method.

To activate an environment created with guild init run:

source guild-env [<env path>]

Activate a virtual environment created using guild init

You may omit <env path> if the environment is defined in the current directory or in a venv subdirectory.

Note Virtual environments created using guild init are standard Python virtual environments and can be activated by sourcing the bin/activate environment. The guild-env command provides a convenient alternative.

To activate an environment created using virtualenv or venv use:

source <env path>/bin/activate

Activate a virtual environment created using virtualenv or venv

To activate a Conda environment use:

conda activate <env name>

For more information about Conda environments, see Conda - Managing environments.

Once activated, you can verify that Guild home is the expected environment by running:

guild check

Confirm that the guild_home attribute reflects the correct directory.