init command

  1. Usage
    1. Requirements
    2. Guild AI
    3. TensorFlow
    4. Resource cache
  2. Options


guild init [OPTIONS] [DIR]

Initialize a Guild environment.

init initializes a Guild environment in DIR, which is the current directory by default.

init creates a virtual environment in DIR using virtualenv.

Use ‑‑python to specify the Python interpreter to use within the generated virtual environment. By default, the default Python interpreter for virtualenv is used unless python is explicitly listed as a requirement. If no‑venv is specified, ‑‑python is ignored.


By default, any required packages listed under packages.requires in guild.yml in the environment parent directory are installed into the environment. Use ‑‑no‑reqs to suppress this behavior.

Additionally, packages defined in requirements.txt in the environment parent directory will be installed. Use ‑‑no‑reqs to suppress this behavior.

Note that packages defined in guild.yml use Guild package names while packages defined in requirements.txt use PyPI package names.

For information in requirements files, see:

You may explicitly specify requirements file using ‑r or ‑‑requirement. If ‑r, ‑‑requirement is specified, Guild will not automatically install packages in requirements.txt -- that file must be specified explicitly in the command.

Guild AI

By default init installs the active version of Guild AI in the initialized environment. To install a different version, or to install a Guild wheel distribution file use the ‑‑guild option.


TensorFlow is installed only if it is listed as a dependency, either explicitly in a requirements file or in package definition of a guild.yml file located in the environment parent directory.

If the special package tensorflow‑any is listed as a Guild package dependency, Guild installs the appropriate package -- either tensorflow or tensorflow‑gpu -- based on the system GPU support. You can specify the package explicitly using ‑‑tensorflow.

Resource cache

By default resources are cached and shared at the user level in ~/.guild/cache/resources so that resources downloaded from one environment are available to other environments. You can modify this behavior to have all resources downloaded local to the environment by specifying ‑‑local‑resource‑cache.


-n, --name NAME

Environment name (default is env parent directory name).

-p, --python VERSION

Version of Python to use for the environment.

-g, --guild VERSION_OR_PATH

Version of Guild AI to use for the environment. By default, the active version of Guild is installed. This value may alternatively be a path to a Guild wheel distribution.

-r, --requirement REQ

Install required package or packages defined in a file. May be used multiple times.

-P, --path DIR

Include DIR as a Python path in the environment.


Don't install from requirements.txt or guild.yml in environment parent directory.

--tensorflow PACKAGE

Install PACKAGE wherever tensorflow-any is required. See TENSORFLOW help for details.

-l, --local-resource-cache

Use a local cache when initializing an environment.

-y, --yes

Initialize a Guild environment without prompting.


Don't show progress when installing environment packages.

--help Show command help and exit.
Guild AI version 0.6.0.dev2