Save runs to project directory

How To Tips
1

Overview

By default, Guild saves runs in ~/.guild/runs as described in Environments.

What if you want to store runs in a project subdirectory?

You can do this using a virtual environment and a symbolic link.

Steps

Step 1. Create a project-local virtual environment

Option 1. Use guild init:

guild init

Option 2. Use virtualenv:

virtualenv venv

Option 3. Use the venv module (Python 3):

python -m venv venv

Option 4. Use Conda:

conda create -p venv

Tip To save disk space, use --system-site-packages when creating the virtual environment with guild init, virtualenv, or venv. This lets the environment access sytem site packages. However, you lose the benefits of package isolation in this case.

Note Add venv to your .gitignores file to avoid accidentally storing the virtual environment files in your source code repository.

Step 2. Create a symbolic link to the runs directory

Create a symbolic link to the Guild runs directory:

ln -s venv/.guild/runs runs

You can use whatever directory name you like. In this case we use runs.

Note Add this link to your .gitignores file to avoid accidentally storing runs in your source code repository.

Step 3. Activate the project-local environment

Guild will not use the environment until you activate it.

If you used guild init to create the environment, activate it by running:

source guild-env

If you used virtualenv or the venv Python module to create the environment:

source venv/bin/activate

If you used Conda to create the environment:

conda activate venv

With an activated environment, all runs are stored in the project directory under venv/.guild/runs. The symbolic link runs gives you convenient access to these runs.

You can deactivate the environment by running deactivate or conda deactivate. This restores your shell to its state prior to environment activating.

Rationale

Guild uses Python virtual environments to define alternative environments. This uses a standard pattern in for controlling the context of commands and software libraries.

Because Guild uses several directories — not just runs — it’s not possible to simply tell Guild to “save runs in this directory”. The easiest way to expose runs is to link to them.

Tip If you find yourself using the runs (or whatever you name it) project subdirectory to access run files, consider using the following Guild commands, which are designed to give you fast access to these files: ls, open, view.

1 Like