Command: init


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 the venv module if available or the virtualenv program if venv is not available.

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 on 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 Version

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.

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.
-s, --system-site-packages Give environment access to system site packages.
-H, --no-isolate Use current Guild home for the environment. Ignored if --guild-home is also specified, this option is ignored.
-h, --guild-home PATH Alternative Guild home location associated with the environment. By default, Guild home is ‘.guild’ in the environment directory.
-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.
--no-reqs Don’t install from requirements.txt or guild.yml in environment parent directory.
-l, --isolate-resources Use a local cache when initializing an environment.
-y, --yes Initialize a Guild environment without prompting.
--no-progress Don’t show progress when installing environment packages.
--pre Install pre-release versions of applicable packages.
--help Show this message and exit.

Guild AI version 0.7.3