A Guild environment is a Python virtual environment used to isolate models and runs. Each environment is a separate file system directory that contains its own set of runs and Python packages.
Environments generally correspond to a project workflow. We recommend using them for your work with Guild as they provide a number of benefits:
- Restrict models to those you’re interested in working with
- Isolate runs associated with a particular project or worflow
- Minimize software package version conflicts and broken dependencies
Create a Guild environment
Use guild init to create a new Guild environment:
By default, Guild create an environment in a directory named
the current working directory. You can optionally specify a different
guild init ENVIRONMENT-DIR
Activate a Guild environment
Once created, a Guild environment must be activated to be used. Activating a Guild environment changes you shell environment to ensure the following are environment specific:
- Python runtime used for commands
- Available Python packages
To activate an environment
env in the current directory, run:
To activate an environment located somewhere else, run:
source guild-env ENVIRONMENT-DIR
Guild environments start with a minimal number of installed Python packages. They do not use system or user site packages.
Initial packages include:
‑‑no‑tensorflowis specified for the
initcommand. See TensorFlow and environments for more information.
Guild installs additional packages if any of the following are true:
‑r, ‑‑requirementoptions with
init. In this case, Guild installs the package requirements listed in each requirement file.
The environment parent directory contains
requirements.txt. In this case,
requirements.txtis implicitly included in the list of requirement files Guild uses for installing packages.
The environment parent directory contains
guild.ymland that file contains a
packagewith a list of required packages. In this case, Guild installs each of the required packages defined in
guild.yml.It also recursively installs required packages defined in inherited Guild files—i.e. Guild files containing model or config definitions that are extended in the initial Guild file.
You can prevent Guild from installing required packages by specifying
TensorFlow and environments
By default, TensorFlow is installed in new environments. Guild detects whether the system supports GPU acceleration and installs the corresponding Python package.
The following options can be used to change this behavior:
tensorflow‑gpupackage even if the system does not support GPU acceleration.
tensorflowpackage even if the system supports GPU acceleration.
Additional Python paths
If you are working with source based Python packages, you can include
the path to each project using
‑p, ‑‑path option when running
For example, let’s suppose you are using an environment to develop a
model in a project located in
~/my‑project and that model requires
Python modules or Guild config defined in another project
~/required‑project. You can use
‑p to add the path to the required
project this way:
guild init ~/my-project -p ~/required-project
When activated, an environment changes the command prompt to display an environment label. By default, Guild uses the name of the environment parent directory. In most cases this is sufficient to identify the environment when active.
If you want to specify a different level, use the
‑l, ‑‑label option
By default, Guild environments share the user-level resource cache
~/.guild/cache/resources. This ensures that resources downloaded
within the activated environment are available outside the
You can use a local resource cache by specifying
‑‑local‑resource‑cache when running
init. This ensures that
resources downloaded within the activated environment are local to
Local resource caches can be used to completely isolate an environment within a system at the cost of both potentially re-downloading resource files as well as duplicating local file storage.
For details on resource cache directories, see Guild home reference.
Environments and project workflow
We recommend using Guild environments whenever running operations, apart from temporary experimentation. Environments isolate both installed packages and runs, ensuring that work in one project doesn’t interfere with other projects.
We recommend the following project workflow conventions:
- Create a default environment in each Guild project directory:
cd $PROJECT_DIR guild init
- When working with a project, change to the directory and activate the environment:
cd $PROJECT_DIR source guild-env
/envin your project
.gitignorefile, if applicable.
If you are certain you no longer need runs associated with a project (e.g. the runs were used for development only) you can delete the environment by deleting the project
rm -rf $PROJECT_DIR/env
Deleting an environment will delete all runs generated while that environment was activated. Take care when deleting Guild environments.