rez-config-plugins

Rez configuration layering and the plugin system — config precedence and merge rules, string expansion, DelayLoad, key settings (packages_path, implicit_packages, caching, package_filter), and the seven plugin types with their discovery mechanisms and entry points. Use when the user asks how to configure rez, why a setting is not taking effect, or how to write or install a plugin. Covers Rez 3.4.0.

Rez configuration and plugins

One-sentence summary: configuration is layered (each source overrides, not replaces, the previous), and everything extensible — shells, build systems, repositories, release hooks — is a plugin discovered either by rezplugins directory layout or by Python entry points.

Skill scope: configuration and plugins. For resolve behavior see rez-resolve; for the CLI see rez-cli.

Configuration precedence

Lowest to highest. Later sources win.

1. rezconfig.py shipped in the rez installation (defaults + documentation for every setting)
2. File pointed at by REZ_CONFIG_FILE — can be a path-like list to read several files
3. $HOME/.rezconfig or $HOME/.rezconfig.py
4. REZ_<SETTING>_JSON environment variable — value must be JSON-encoded
5. REZ_<SETTING> environment variable — e.g. REZ_PACKAGES_PATH overrides packages_path. Takes precedence over the _JSON form when both are present.
6. (build/release only) the package's own config section via scope("config")

Related: REZ_DISABLE_HOME_CONFIG skips the home config.

Verify what actually took effect:

bash

rez-config                 # dump all settings
rez-config packages_path   # one setting

Merge rules

Sources merge; they do not replace wholesale.

• Dicts are merged recursively.
• Non-dicts override the previous value.

To append/prepend to a list setting instead of replacing it, use ModifyList:

python

release_hooks = ModifyList(append=["custom_release_notify"])

prepend=[...] is also supported.

File formats

Both YAML (.rezconfig) and Python (.rezconfig.py) are supported. Choose Python when settings must vary by platform. You only need to list settings that differ from the defaults.

String expansion

Applied to all configuration settings:

• Environment variables: ${HOME}
• system object properties: {system.platform}, {system.arch}, {system.os}

DelayLoad

Keep a large setting out of the main config and load it only when referenced (YAML or JSON):

python

default_relocatable_per_package = DelayLoad('/svr/configs/rez_relocs.yaml')

Settings that matter most

Setting	Default	Purpose
packages_path	see install	package search path
local_packages_path	~/packages	where rez-build --install lands
release_packages_path	~/.rez/packages/int	where rez-release deploys
cache_packages_path	None	package cache location
implicit_packages	~platform=={system.platform}, ~arch=={system.arch}, ~os=={system.os}	weak system constraints
variant_select_mode	version_priority	variant preference strategy
plugin_path	[]	where to find rezplugins
package_filter	None	hide packages from resolves
package_definition_python_path	None	extra import path for package.py
resolve_caching	True	cache resolves
cache_package_files / cache_listdir	True	filesystem caches
default_cachable	False	whether packages may be cached
memcached_uri	[]	back the caches with memcached
error_on_missing_variant_requires	True	fail on incomplete variant requirements
pathed_env_vars	any var ending in PATH	which vars get path-normalized
rez_1_environment_variables	False	legacy variable naming
warn_old_commands / error_old_commands	True / False	old-style commands detection

The full, authoritative list with documentation lives in src/rez/rezconfig.py in the rez source.

Plugins

Plugin types and their base classes:

Type	Base class	Top-level settings
build_process	rez.build_process.BuildProcess or BuildProcessHelper	No
build_system	rez.build_system.BuildSystem	No
command	rez.command.Command	Yes
package_repository	rez.package_repository.PackageRepository + 3 package_resources classes	No
release_hook	rez.release_hook.ReleaseHook	Yes
release_vcs	rez.release_vcs.ReleaseVCS	Yes
shell	rez.shells.Shell	No

Built-ins live in src/rezplugins. New plugins are encouraged out-of-tree.

List what is installed and its load status:

bash

rez -i

Example output — note release vcs / svn / FAILED: No module named 'pysvn', i.e. rez -i is the quickest way to see a plugin that failed to import.

Configuring plugins

python

plugins = {
    "package_repository": {
        "filesystem": {}
    }
}

Discovery mechanism 1 — rezplugins directory layout

Point plugin_path (or REZ_PLUGIN_PATH) at the directory above your rezplugins dir:

text

rezplugins/
├── __init__.py
└── <plugin_type>/
    ├── __init__.py
    └── <plugin name>.py

The rezplugins directory name is not optional, and your sparse copy must be on REZ_PLUGIN_PATH only — not on PYTHONPATH. That ordering guarantees rez's own copy of rezplugins is found first.

Discovery mechanism 2 — entry points (rez 3.3.0+)

One entry point per plugin type:

• rez.plugins.build_process
• rez.plugins.build_system
• rez.plugins.command
• rez.plugins.package_repository
• rez.plugins.release_hook
• rez.plugins.release_vcs
• rez.plugins.shell

This is the more flexible option: no special file layout, and one package can ship several plugins of different types.

Default settings for a plugin

Ship a rezconfig.py or rezconfig.yml beside the plugin module; rez loads it automatically.

python

top_level_setting = "value"

plugin_name = {
    "setting_1": "value1"
}

plugin_name settings arrive as self.settings; top_level_setting as self.type_settings.top_level_setting. Only the types marked "Yes" in the table above support top-level settings.

Overriding built-ins

Install a plugin with the same name and type as a built-in and rez prefers yours. This is the supported way to modify built-in behavior without patching rez source.

Troubleshooting

Symptom	Check
Setting not taking effect	walk the precedence list; REZ_<SETTING> beats the _JSON form and beats files
Home config interfering	REZ_DISABLE_HOME_CONFIG, or inspect with rez-config
List setting got replaced not extended	use ModifyList(append=[...])
Plugin not found	rez -i; confirm REZ_PLUGIN_PATH points above rezplugins
Plugin import error	rez -i shows FAILED: <error> in the status column
Packages silently missing from resolves	package_filter, rez-pkg-ignore, packages_path order
Resolves look stale	resolve_caching; retest with rez-env --no-cache

Agent workflow

1. Confirm the effective value with rez-config <setting> before changing anything.
2. Prefer environment variables for one-off overrides, REZ_CONFIG_FILE for site-wide policy.
3. Use ModifyList whenever you mean "add to" rather than "replace".
4. Check rez -i before debugging a plugin by hand.
5. Put new plugins in entry-point packages unless you specifically need the directory layout.