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 forguild_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
ifrequirements.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 thebin/activate
environment. Theguild-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.