Configuring rez#

Rez has a good number of configurable settings. The default settings, and documentation for every setting, can be found src/rez/rezconfig.py.

Settings are determined in the following way:

The setting is first read from the file rezconfig.py in the rez installation;
The setting is then overridden if it is present in another settings file pointed at by the REZ_CONFIG_FILE environment variable. This can also be a path-like variable, to read from multiple configuration files;
The setting is further overriden if it is present in $HOME/.rezconfig;
The setting is overridden again if the environment variable REZ_XXX is present, where XXX is the uppercase version of the setting key. For example, image_viewer will be overriden by REZ_IMAGE_VIEWER.
This is a special case applied only during a package build or release. In this case, if the package definition file contains a “config” section, settings in this section will override all others. See Package Overrides.

It is fairly typical to provide your site-specific rez settings in a file that the environment variable REZ_CONFIG_FILE is then set to for all your users.

Tip

You do not need to provide a copy of all settings in this file. Just provide those that are changed from the defaults.

Supported Configuration File Formats#

Rez supports both YAML configuration files and Python configuration files.

You may prefer a Python based configuration file if you need to vary your configuration settings based on your current platform.

Settings Merge Rules#

When multiple configuration sources are present, the settings are merged together - one config file does not replace the previous one, it overrides it. By default, the following rules apply:

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

However, it is also possible to append and/or prepend list-based settings by using the ModifyList class. For example, the following config entry will append to the release_hooks setting value defined by the previous configuration sources (you can also supply a prepend argument):

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

Package Overrides#

Packages themselves can override configuration settings. To show how this is useful, consider the following example:

# in package.py
with scope("config") as c:
    c.release_packages_path = "/svr/packages/internal"

Here a package is overriding the default release path - perhaps you’re releasing internally- and externally-developed packages to different locations, for example.

These config overrides are only applicable during building and releasing of the package. As such, even though any setting can be overridden, it’s only useful to do so for those that have any effect during the build/install process. These include:

Settings that determine where packages are found, such as packages_path, local_packages_path and release_packages_path;
Settings in the build_system, release_hook and release_vcs plugin types;
package_definition_python_path;
package_filter.

String Expansions#

The following string expansions occur on all configuration settings:

Any environment variable reference, in the form ${HOME};
Any property of the system object, eg {system.platform}. See rez.system.System for more details.

Delay Load#

It is possible to store a config setting in a separate file, which will be loaded only when that setting is referenced. This can be useful if you have a large value (such as a dict) that you don’t want to pollute the main config with. YAML and JSON formats are supported:

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

See DelayLoad.

Commandline Tool#

You can use the rez-config command line tool to see what the current configured settings are. Called with no arguments, it prints all settings; if you specify an argument, it prints out just that setting:

]$ rez-config packages_path
- /home/sclaus/packages
- /home/sclaus/.rez/packages/int
- /home/sclaus/.rez/packages/ext

Here is an example showing how to override settings using your own configuration file:

]$ echo 'packages_path = ["~/packages", "/packages"]' > myrezconfig.py
]$ export REZ_CONFIG_FILE=${PWD}/myrezconfig.py
]$ rez-config packages_path
- /home/sclaus/packages
- /packages

Configuration Settings#

Following is an alphabetical list of rez settings.

Note

Note that this list has been generated automatically from the src/rez/rezconfig.py file in the rez source, so you can also refer to that file for the same information.

Paths#

context_tmpdir = None#

Where temporary files for contexts go. Defaults to appropriate path depending on your system. For example, *nix distributions will probably set this to /tmp. This is separate to tmpdir because you sometimes might want to set this to an NFS location. For example, perhaps rez is used during a render and you’d like to store these tempfiles in the farm queuer’s designated tempdir so they’re cleaned up when the render completes.

REZ_CONTEXT_TMPDIR#: The REZ_CONTEXT_TMPDIR environment variable can also be used to configure this.

local_packages_path = "~/packages"#

The path that Rez will locally install packages to when rez-build is used

REZ_LOCAL_PACKAGES_PATH#: The REZ_LOCAL_PACKAGES_PATH environment variable can also be used to configure this.

package_definition_build_python_paths = []#

These are extra python paths that are added to sys.path only during a build. This means that any of the functions in the following list can import modules from these paths:

The preprocess() function;
Any function decorated with @early. These get evaluated at build time.

You can use this to provide common code to your package definition files during a build. To provide common code for packages to use at resolve time instead (for example, in a commands() function) see the following package_definition_python_path setting.

REZ_PACKAGE_DEFINITION_BUILD_PYTHON_PATHS#: The REZ_PACKAGE_DEFINITION_BUILD_PYTHON_PATHS environment variable can also be used to configure this.

package_definition_python_path = None#

This is the directory from which installed packages can import modules. This is a way for packages to use shared code.

This is NOT a standard path added to sys.path. Packages that use modules from within this directory need to explicitly name them. Furthermore, modules that a package uses are copied into that package’s install. This ensures that the package remains standalone and that changes to the shared code will not break or alter existing package installs.

Consider the setting:

package_definition_python_path = "/src/rezutils"

Consider also the following package commands() function:

@include("utils")
def commands():
    utils.do_some_common_thing(this)

This package will import the code from /src/rezutils/utils.py (or more specifically, its copy of this sourcefile) and will bind it to the name utils.

For further information, see Sharing Code Across Package Definition Files.

REZ_PACKAGE_DEFINITION_PYTHON_PATH#: The REZ_PACKAGE_DEFINITION_PYTHON_PATH environment variable can also be used to configure this.

packages_path#

Default:

[
    "~/packages",           # locally installed pkgs, not yet deployed
    "~/.rez/packages/int",  # internally developed pkgs, deployed
    "~/.rez/packages/ext",  # external (3rd party) pkgs, such as houdini, boost
]

The package search path. Rez uses this to find packages. A package with the same name and version in an earlier path takes precedence.

REZ_PACKAGES_PATH#: The REZ_PACKAGES_PATH environment variable can also be used to configure this.

release_packages_path = "~/.rez/packages/int"#

The path that Rez will deploy packages to when rez-release is used. For production use, you will probably want to change this to a site-wide location.

REZ_RELEASE_PACKAGES_PATH#: The REZ_RELEASE_PACKAGES_PATH environment variable can also be used to configure this.

tmpdir = None#

Where temporary files go. Defaults to appropriate path depending on your system. For example, *nix distributions will probably set this to /tmp. It is highly recommended that this be set to local storage, such as /tmp.

REZ_TMPDIR#: The REZ_TMPDIR environment variable can also be used to configure this.

Extensions#

bind_module_path = []#

Search path for bind modules. The rez-bind tool uses these modules to create rez packages that reference existing software already installed on the system.

REZ_BIND_MODULE_PATH#: The REZ_BIND_MODULE_PATH environment variable can also be used to configure this.

plugin_path = []#

Search path for rez plugins.

REZ_PLUGIN_PATH#: The REZ_PLUGIN_PATH environment variable can also be used to configure this.

Caching#

cache_listdir = True#

Cache directory traversals to memcached, if enabled. Updated directory entries will still be read correctly (ie, the cache invalidates when the filesystem changes).

REZ_CACHE_LISTDIR#: The REZ_CACHE_LISTDIR environment variable can also be used to configure this.

cache_package_files = True#

Cache package file reads to memcached, if enabled. Updated package files will still be read correctly (ie, the cache invalidates when the filesystem changes).

REZ_CACHE_PACKAGE_FILES#: The REZ_CACHE_PACKAGE_FILES environment variable can also be used to configure this.

memcached_context_file_min_compress_len = 1#

Bytecount beyond which memcached entries are compressed, for cached context files (aka .rxt files). Zero means never compress.

REZ_MEMCACHED_CONTEXT_FILE_MIN_COMPRESS_LEN#: The REZ_MEMCACHED_CONTEXT_FILE_MIN_COMPRESS_LEN environment variable can also be used to configure this.

memcached_listdir_min_compress_len = 16384#

Bytecount beyond which memcached entries are compressed, for directory listings. Zero means never compress.

REZ_MEMCACHED_LISTDIR_MIN_COMPRESS_LEN#: The REZ_MEMCACHED_LISTDIR_MIN_COMPRESS_LEN environment variable can also be used to configure this.

memcached_package_file_min_compress_len = 16384#

Bytecount beyond which memcached entries are compressed, for cached package files (such as package.yaml, package.py). Zero means never compress.

REZ_MEMCACHED_PACKAGE_FILE_MIN_COMPRESS_LEN#: The REZ_MEMCACHED_PACKAGE_FILE_MIN_COMPRESS_LEN environment variable can also be used to configure this.

memcached_resolve_min_compress_len = 1#

Bytecount beyond which memcached entries are compressed, for resolves. Zero means never compress.

REZ_MEMCACHED_RESOLVE_MIN_COMPRESS_LEN#: The REZ_MEMCACHED_RESOLVE_MIN_COMPRESS_LEN environment variable can also be used to configure this.

memcached_uri = []#

Uris of running memcached server(s) to use as a file and resolve cache. For example, the URI 127.0.0.1:11211 points to memcached running on localhost on its default port. Must be either None, or a list of strings.

REZ_MEMCACHED_URI#: The REZ_MEMCACHED_URI environment variable can also be used to configure this.

resolve_caching = True#

Cache resolves to memcached, if enabled. Note that these cache entries will be correctly invalidated if, for example, a newer package version is released that would change the result of an existing resolve.

REZ_RESOLVE_CACHING#: The REZ_RESOLVE_CACHING environment variable can also be used to configure this.

resource_caching_maxsize = -1#

The size of the local (in-process) resource cache. Resources include package families, packages and variants. A value of 0 disables caching; -1 sets a cache of unlimited size. The size refers to the number of entries, not byte count.

REZ_RESOURCE_CACHING_MAXSIZE#: The REZ_RESOURCE_CACHING_MAXSIZE environment variable can also be used to configure this.

Package Copy#

default_relocatable = True#

Whether a package is relocatable or not, if it does not explicitly state with the relocatable attribute in its package definition file.

REZ_DEFAULT_RELOCATABLE#: The REZ_DEFAULT_RELOCATABLE environment variable can also be used to configure this.

default_relocatable_per_package = None#

Set relocatable on a per-package basis. This is here for migration purposes. It’s better for packages themselves to set their relocatable attribute. Overrides default_relocatable if a package matches.

Example:

default_relocatable_per_package = {
    "nuke": False,
    "maya": True
}

REZ_DEFAULT_RELOCATABLE_PER_PACKAGE#: The REZ_DEFAULT_RELOCATABLE_PER_PACKAGE environment variable can also be used to configure this.

default_relocatable_per_repository = None#

Set relocatable on a per-package-repository basis. Overrides default_relocatable_per_package and default_relocatable for any repos listed here.

Example:

default_relocatable_per_repostitory = {
    '/svr/packages': False
}

REZ_DEFAULT_RELOCATABLE_PER_REPOSITORY#: The REZ_DEFAULT_RELOCATABLE_PER_REPOSITORY environment variable can also be used to configure this.

Package Caching#

Package caching refers to copying variant payloads to a path on local disk, and using those payloads instead. It is a way to avoid fetching files over shared storage, and is unrelated to memcached-based caching of resolves and package definitions as seen in the “Caching” config section.

cache_packages_path = None#

The path where rez locally caches variants. If this is None, then package caching is disabled.

REZ_CACHE_PACKAGES_PATH#: The REZ_CACHE_PACKAGES_PATH environment variable can also be used to configure this.

default_cachable = False#

Whether a package is cachable or not, if it does not explicitly state with the cachable attribute in its package definition file. If None, defaults to packages’ relocatability (ie cachable == relocatable).

REZ_DEFAULT_CACHABLE#: The REZ_DEFAULT_CACHABLE environment variable can also be used to configure this.

default_cachable_per_package = None#

Set cachable on a per-package basis. This is here for migration purposes. It’s better for packages themselves to set their cachable attribute. Overrides default_cachable if a package matches.

Example:

default_cachable_per_package = {
    "nuke": False,
    "maya": True
}

REZ_DEFAULT_CACHABLE_PER_PACKAGE#: The REZ_DEFAULT_CACHABLE_PER_PACKAGE environment variable can also be used to configure this.

default_cachable_per_repository = None#

Set cachable on a per-package-repository basis. Overrides default_cachable_per_package and default_cachable for any repos listed here.

Example:

default_cachable_per_repostitory = {
    '/svr/packages': False
}

REZ_DEFAULT_CACHABLE_PER_REPOSITORY#: The REZ_DEFAULT_CACHABLE_PER_REPOSITORY environment variable can also be used to configure this.

package_cache_clean_limit = 0.5#

If > 0, spend up to this many seconds cleaning the cache every time the cache is updated. This is a way to keep the cache size under control without having to periodically run rez-pkg-cache --clean. Set to -1 to disable.

REZ_PACKAGE_CACHE_CLEAN_LIMIT#: The REZ_PACKAGE_CACHE_CLEAN_LIMIT environment variable can also be used to configure this.

package_cache_during_build = False#

Enable package caching during a package build.

REZ_PACKAGE_CACHE_DURING_BUILD#: The REZ_PACKAGE_CACHE_DURING_BUILD environment variable can also be used to configure this.

package_cache_local = False#

Allow caching of local packages. You would only want to set this True for testing purposes.

REZ_PACKAGE_CACHE_LOCAL#: The REZ_PACKAGE_CACHE_LOCAL environment variable can also be used to configure this.

package_cache_log_days = 7#

Number of days of package cache logs to keep. Logs are written to pkg-cache-root/.sys/log/filename.log

REZ_PACKAGE_CACHE_LOG_DAYS#: The REZ_PACKAGE_CACHE_LOG_DAYS environment variable can also be used to configure this.

package_cache_max_variant_days = 30#

Delete variants that haven’t been used in N days (see rez-pkg-cache --clean). To disable, set to zero.

REZ_PACKAGE_CACHE_MAX_VARIANT_DAYS#: The REZ_PACKAGE_CACHE_MAX_VARIANT_DAYS environment variable can also be used to configure this.

package_cache_same_device = False#

Allow package caching if the source package is on the same physical disk as the package cache itself. You would only want to set this True for testing purposes.

REZ_PACKAGE_CACHE_SAME_DEVICE#: The REZ_PACKAGE_CACHE_SAME_DEVICE environment variable can also be used to configure this.

read_package_cache = True#

If True, variants in a resolve will use locally cached payloads if they are present in the cache.

REZ_READ_PACKAGE_CACHE#: The REZ_READ_PACKAGE_CACHE environment variable can also be used to configure this.

write_package_cache = True#

If True, creating or sourcing a context will cause variants to be cached.

REZ_WRITE_PACKAGE_CACHE#: The REZ_WRITE_PACKAGE_CACHE environment variable can also be used to configure this.

Package Resolution#

allow_unversioned_packages = True#

If True, unversioned packages are allowed. Solve times are slightly better if this value is False.

REZ_ALLOW_UNVERSIONED_PACKAGES#: The REZ_ALLOW_UNVERSIONED_PACKAGES environment variable can also be used to configure this.

error_on_missing_variant_requires = True#

Defines whether a resolve should immediately fail if any variants have a required package that can’t be found. This can be useful to disable if you have packages that aren’t available to all users. It is enabled by default. If a variant has requires that cannot be found , it will error immediately rather than trying the other variants. If disabled, it will try other variants before giving up.

Warning

Memcached isn’t tested with scenarios where you expect users to have access to different sets of packages. It expects that every user can access the same set of packages, which may cause incorrect resolves when this option is disabled.

REZ_ERROR_ON_MISSING_VARIANT_REQUIRES#: The REZ_ERROR_ON_MISSING_VARIANT_REQUIRES environment variable can also be used to configure this.

implicit_packages#

Default:

[
    "~platform=={system.platform}",
    "~arch=={system.arch}",
    "~os=={system.os}",
]

Packages that are implicitly added to all package resolves, unless the rez-env --no-implicit flag is used.

REZ_IMPLICIT_PACKAGES#: The REZ_IMPLICIT_PACKAGES environment variable can also be used to configure this.

package_filter = None#

One or more filters can be listed, each with a list of exclusion and inclusion rules. These filters are applied to each package during a resolve, and if any filter excludes a package, that package is not included in the resolve. Here is a simple example:

package_filter = {
    'excludes': 'glob(*.beta)',
    'includes': 'glob(foo-*)',
}

This is an example of a single filter with one exclusion rule and one inclusion rule. The filter will ignore all packages with versions ending in .beta, except for package foo (which it will accept all versions of). A filter will only exclude a package if that package matches at least one exclusion rule, and does not match any inclusion rule.

Here is another example, which excludes all beta and dev packages, and all packages except foo that are released after a certain date. Note that in order to use multiple filters, you need to supply a list of dicts, rather than just a dict:

package_filter = [
    {
        'excludes': ['glob(*.beta)', 'glob(*.dev)']
    },
    {
        'excludes': ['after(1429830188)'],
        'includes': ['foo'],  # same as range(foo), same as glob(foo-*)
    }
]

This example shows why multiple filters are supported. With only one filter, it would not be possible to exclude all beta and dev packages (including foo), but also exclude all packages after a certain date, except for foo.

Following are examples of all the possible rules:

Example	Description
`glob(*.beta)`	Matches packages matching the glob pattern.
`regex(.*-\\.beta)`	Matches packages matching re-style regex.
`range(foo-5+)`	Matches packages within the given requirement.
`before(1429830188)`	Matches packages released before the given date.
`after(1429830188)`	Matches packages released after the given date.
`*.beta`	Same as glob(*.beta).
`foo-5+`	Same as range(foo-5+).

REZ_PACKAGE_FILTER#: The REZ_PACKAGE_FILTER environment variable can also be used to configure this.

package_orderers = None#

One or more “orderers” can be listed. This will affect the order of version resolution. This can be used to ensure that specific version have priority over others. Higher versions can still be accessed if explicitly requested.

A common use case is to ease migration from python-2 to python-3:

package_orderers = [
    {
       "type": "per_family",
       "orderers": [
            {
                "packages": ["python"],
                "type": "version_split",
                "first_version": "2.7.16"
            }
        ]
    }
]

This will ensure that for the “python” package, versions equals or lower than “2.7.16” will have priority. Considering the following versions: “2.7.4”, “2.7.16”, “3.7.4”:

Example	Result
rez-env python	python-2.7.16
rez-env python-3	python-3.7.4

Package orderers will also apply to variants of packages. Consider a package “pipeline-1.0” which has the following variants: [["python-2.7.4", "python-2.7.16", "python-3.7.4"]]

Example	Result
rez-env pipeline	pipeline-1.0 python-2.7.16
rez-env pipeline python-3	pipeline-1.0 python-3.7.4

Here’s another example, using another orderer: “soft_timestamp”. This orderer will prefer packages released before a provided timestamp. The following example will prefer package released before 2019-09-09.

package_orderers = [
    {
        "type": "soft_timestamp",
        "timestamp": 1568001600,  # 2019-09-09
        "rank": 3
    }
]

A timestamp can be generated with python:

$ python -c "import datetime, time; print(int(time.mktime(datetime.date(2019, 9, 9).timetuple())))"
1568001600

The rank can be used to allow some versions released after the timestamp to still be considered. When using semantic versionnng, a value of 3 is the most common. This will let version with a different patch number to be accepted.

Considering a package “foo” with the following versions:

“1.0.0” was released at 2019-09-07
“2.0.0” was released at 2019-09-08
“2.0.1” was released at 2019-09-10
“2.1.0” was released at 2019-09-11
“3.0.0” was released at 2019-09-12

Example	Timestamp	Rank	Result
rez-env foo	2019-09-09	0	foo-2.0.0
rez-env foo	2019-09-09	3	foo-2.0.1
rez-env foo	2019-09-09	2	foo-2.1.0
rez-env foo	2019-09-09	1	foo-3.0.0

REZ_PACKAGE_ORDERERS#: The REZ_PACKAGE_ORDERERS environment variable can also be used to configure this.

platform_map = {}#

Override platform values from Platform.os and arch. This is useful as Platform.os might show different values depending on the availability of lsb-release on the system. The map supports regular expression, e.g. to keep versions.

Note

The following examples are not necessarily recommendations.

platform_map = {
    "os": {
        r"Scientific Linux-(.*)": r"Scientific-\1",                 # Scientific Linux-x.x -> Scientific-x.x
        r"Ubuntu-14.\d": r"Ubuntu-14",                              # Any Ubuntu-14.x      -> Ubuntu-14
        r'CentOS Linux-(\d+)\.(\d+)(\.(\d+))?': r'CentOS-\1.\2', '  # Centos Linux-X.Y.Z -> CentOS-X.Y
    },
    "arch": {
        "x86_64": "64bit",                                          # Maps both x86_64 and amd64 -> 64bit
        "amd64": "64bit",
    },
}

REZ_PLATFORM_MAP#: The REZ_PLATFORM_MAP environment variable can also be used to configure this.

prune_failed_graph = True#

If true, then when a resolve graph is generated during a failed solve, packages unrelated to the failure are pruned from the graph. An “unrelated” package is one that is not a dependency ancestor of any packages directly involved in the failure.

REZ_PRUNE_FAILED_GRAPH#: The REZ_PRUNE_FAILED_GRAPH environment variable can also be used to configure this.

variant_select_mode = "version_priority"#

Variant select mode. This determines which variants in a package are preferred during a solve. Valid options are:

version_priority: Prefer variants that contain higher versions of packages present in the request;
intersection_priority: Prefer variants that contain the most number of packages that are present in the request.

As an example, suppose you have a package foo which has two variants:

variants = [
    ["bar-3.0", "baz-2.1"],
    ["bar-2.8", "burgle-1.0"]
]

if you do rez-env foo bar then, in either variant_select_mode, it will prefer the first variant, ["bar-3.0", "baz-2.1"], because it has a higher version of the first variant requirement (bar). However, if we instead do rez-env foo bar burgle we get different behavior. version_priority mode will still return ["bar-3.0", "baz-2.1"], because the first requirement’s version is higher.

However, intersection_priority mode will pick the second variant, ["bar-2.8", "burgle-1.0"], because it contains more packages that were in the original request (burgle).

REZ_VARIANT_SELECT_MODE#: The REZ_VARIANT_SELECT_MODE environment variable can also be used to configure this.

Environment Resolution#

all_parent_variables = False#

See parent_variables.

REZ_ALL_PARENT_VARIABLES#: The REZ_ALL_PARENT_VARIABLES environment variable can also be used to configure this.

all_resetting_variables = False#

See resetting_variables.

REZ_ALL_RESETTING_VARIABLES#: The REZ_ALL_RESETTING_VARIABLES environment variable can also be used to configure this.

default_shell = ""#

The default shell type to use when creating resolved environments (eg when using rez-env, or calling ResolvedContext.execute_shell()). If empty or None, the current shell is used (for eg, “bash”).

Changed in version 3.0.0: The default value on Windows was changed to “powershell”.

REZ_DEFAULT_SHELL#: The REZ_DEFAULT_SHELL environment variable can also be used to configure this.

env_var_separators#

Default:

{
    "CMAKE_MODULE_PATH": ";",
    "DOXYGEN_TAGFILES": " ",
}

This setting can be used to override the separator used for environment variables that represent a list of items. By default, the value of os.pathsep will be used, unless the environment variable is list here, in which case the configured separator will be used.

REZ_ENV_VAR_SEPARATORS#: The REZ_ENV_VAR_SEPARATORS environment variable can also be used to configure this.

new_session_popen_args = None#

subprocess.Popen arguments to use in order to execute a shell in a new process group (see ResolvedContext.execute_shell() and its start_new_session argument). Dict of (Popen argument, value).

REZ_NEW_SESSION_POPEN_ARGS#: The REZ_NEW_SESSION_POPEN_ARGS environment variable can also be used to configure this.

package_commands_sourced_first = True#

Defines when package commands are sourced during the startup sequence of an interactive shell. If True, package commands are sourced before startup scripts (such as .bashrc). If False, package commands are sourced after.

REZ_PACKAGE_COMMANDS_SOURCED_FIRST#: The REZ_PACKAGE_COMMANDS_SOURCED_FIRST environment variable can also be used to configure this.

package_preprocess_function = None#

If you define this function, by default it will be called as the preprocess function on every package that does not provide its own, as part of the build process. This behavior can be changed by using the package_preprocess_mode setting so that it gets executed even if a package define its own preprocess function.

The setting can be a function defined in your rezconfig.py, or a string.

Example of a function to define the setting:

# in your rezconfig.py
def package_preprocess_function(this, data):
    # some custom code...

In the case where the function is a string, it must be made available by setting the value of package_definition_build_python_paths appropriately.

For example, consider the settings:

package_definition_build_python_paths = ["/src/rezutils"]
package_preprocess_function = "build.validate"

This would use the validate function in the sourcefile /src/rezutils/build.py to preprocess every package definition file that does not define its own preprocess function.

If the preprocess function raises an exception, an error message is printed, and the preprocessing is not applied to the package. However, if the InvalidPackageError exception is raised, the build is aborted.

You would typically use this to perform common validation or modification of packages. For example, your common preprocess function might check that the package name matches a regex. Here’s what that might look like:

# in /src/rezutils/build.py
import re
from rez.exceptions import InvalidPackageError

def validate(package, data):
    regex = re.compile("(a-zA-Z_)+$")
    if not regex.match(package.name):
        raise InvalidPackageError("Invalid package name.")

REZ_PACKAGE_PREPROCESS_FUNCTION#: The REZ_PACKAGE_PREPROCESS_FUNCTION environment variable can also be used to configure this.

package_preprocess_mode = "override"#

Defines in which order the package_preprocess_function and the preprocess function inside a package.py are executed.

Note that “global preprocess” means the preprocess defined by package_preprocess_function.

Possible values are:

“before”: Package’s preprocess function is executed before the global preprocess;
“after”: Package’s preprocess function is executed after the global preprocess;
“override”: Package’s preprocess function completely overrides the global preprocess.

REZ_PACKAGE_PREPROCESS_MODE#: The REZ_PACKAGE_PREPROCESS_MODE environment variable can also be used to configure this.

parent_variables = []#

Rez’s default behaviour is to overwrite variables on first reference. This prevents unconfigured software from being used within the resolved environment. For example, if PYTHONPATH were to be appended to and not overwritten, then python modules from the parent environment would be (incorrectly) accessible within the Rez environment.

“Parent variables” override this behaviour. They are appended/prepended to, rather than being overwritten. If you set all_parent_variables to True, then all variables are considered parent variables, and the value of parent_variables is ignored. Be aware that if you make variables such as PATH, PYTHONPATH or app plugin paths parent variables, you are exposing yourself to potentially incorrect behaviour within a resolved environment.

REZ_PARENT_VARIABLES#: The REZ_PARENT_VARIABLES environment variable can also be used to configure this.

pathed_env_vars#

Default:

[
    "*PATH"
]

This setting identifies path-like environment variables. This is required because some shells need to apply path normalization. For example, the command env.PATH.append("{root}/bin") will be normalized to (eg) C:\...\bin in a cmd shell on Windows. Note that wildcards are supported. If this setting is not correctly configured, then your shell may not work correctly.

REZ_PATHED_ENV_VARS#: The REZ_PATHED_ENV_VARS environment variable can also be used to configure this.

resetting_variables = []#

When two or more packages in a resolve attempt to set the same environment variable, Rez’s default behaviour is to flag this as a conflict and abort the resolve. You can overcome this in a package’s commands section by using the Rex command resetenv() instead of setenv(). However, you can also turn off this behaviour globally for some varibles by adding them to resetting_variables, and for all variables, by setting all_resetting_variables to true.

REZ_RESETTING_VARIABLES#: The REZ_RESETTING_VARIABLES environment variable can also be used to configure this.

rez_tools_visibility = "append"#

Defines how Rez’s command line tools are added back to $PATH within a resolved environment. Valid values are:

“append”: Rez tools are appended to PATH (default);
“prepend”: Rez tools are prepended to PATH;
“never”: Rez tools are not added back to PATH. Rez will not be available within resolved shells.

REZ_REZ_TOOLS_VISIBILITY#: The REZ_REZ_TOOLS_VISIBILITY environment variable can also be used to configure this.

standard_system_paths = []#

Defines paths to initially set $PATH to, if a resolve appends/prepends $PATH. If this is an empty list, then this initial value is determined automatically depending on the shell (for example, *nix shells create a temp clean shell and get $PATH from there; Windows inspects its registry).

REZ_STANDARD_SYSTEM_PATHS#: The REZ_STANDARD_SYSTEM_PATHS environment variable can also be used to configure this.

suite_visibility = "always"#

Defines what suites on $PATH stay visible when a new rez environment is resolved. Possible values are:

“never”: Don”t attempt to keep any suites visible in a new env
“always”: Keep suites visible in any new env
“parent”: Keep only the parent suite of a tool visible
“parent_priority”: Keep all suites visible and the parent takes precedence

REZ_SUITE_VISIBILITY#: The REZ_SUITE_VISIBILITY environment variable can also be used to configure this.

terminal_emulator_command = None#

The command to use to launch a new Rez environment in a separate terminal (this is enabled using the rez-env --detached option). If None, it is detected.

REZ_TERMINAL_EMULATOR_COMMAND#: The REZ_TERMINAL_EMULATOR_COMMAND environment variable can also be used to configure this.

Context Tracking#

context_tracking_amqp#

Default:

{
    "userid": '',
    "password": '',
    "connect_timeout": 10,
    "exchange_name": '',
    "exchange_routing_key": 'REZ.CONTEXT',
    "message_delivery_mode": 1
}

See context_tracking_host

REZ_CONTEXT_TRACKING_AMQP#: The REZ_CONTEXT_TRACKING_AMQP environment variable can also be used to configure this.

context_tracking_context_fields#

Default:

[
    "status",
    "timestamp",
    "solve_time",
    "load_time",
    "from_cache",
    "package_requests",
    "implicit_packages",
    "resolved_packages"
]

See context_tracking_host

REZ_CONTEXT_TRACKING_CONTEXT_FIELDS#: The REZ_CONTEXT_TRACKING_CONTEXT_FIELDS environment variable can also be used to configure this.

context_tracking_extra_fields = {}#

See context_tracking_host

REZ_CONTEXT_TRACKING_EXTRA_FIELDS#: The REZ_CONTEXT_TRACKING_EXTRA_FIELDS environment variable can also be used to configure this.

context_tracking_host = ''#

Send data to AMQP server whenever a context is created or sourced. The payload is like so:

{
    "action": "created",
    "host": "some_fqdn",
    "user": "${USER}",
    "context": {
        ...
    }
}

Action is one of (created, sourced). Routing key is set to {exchange_routing_key}.{action|upper}, eg REZ.CONTEXT.SOURCED. created is when a new context is constructed, which will either cause a resolve to occur, or fetches a resolve from the cache. sourced is when an existing context is recreated (eg loading an rxt file).

The context field contains the context itself (the same as what is present in an rxt file), filtered by the fields listed in context_tracking_context_fields.

Tracking is enabled if context_tracking_host is non-empty. Set to stdout to just print the message to standard out instead, for testing purposes. Otherwise, {host}[:{port}] is expected.

If any items are present in context_tracking_extra_fields, they are added to the payload. If any extra field contains references to unknown env-vars, or is set to an empty string (possibly due to var expansion), it is removed from the message payload.

REZ_CONTEXT_TRACKING_HOST#: The REZ_CONTEXT_TRACKING_HOST environment variable can also be used to configure this.

Debugging#

catch_rex_errors = True#

When an error is encountered in rex code, rez catches the error and processes it, removing internal info (such as the stacktrace inside rez itself) that is generally not interesting to the package author. If set to False, rex errors are left uncaught, which can be useful for debugging purposes.

REZ_CATCH_REX_ERRORS#: The REZ_CATCH_REX_ERRORS environment variable can also be used to configure this.

debug_all = False#

Turn on all debugging messages

REZ_DEBUG_ALL#: The REZ_DEBUG_ALL environment variable can also be used to configure this.

debug_bind_modules = False#

Print debugging info in binding modules. Binding modules should print using the bind_utils.log() function - it is controlled with this setting

REZ_DEBUG_BIND_MODULES#: The REZ_DEBUG_BIND_MODULES environment variable can also be used to configure this.

debug_context_tracking = False#

Print debugging info when an AMPQ server is used in context tracking

REZ_DEBUG_CONTEXT_TRACKING#: The REZ_DEBUG_CONTEXT_TRACKING environment variable can also be used to configure this.

debug_file_loads = False#

Print info whenever a file is loaded from disk, or saved to disk.

REZ_DEBUG_FILE_LOADS#: The REZ_DEBUG_FILE_LOADS environment variable can also be used to configure this.

debug_memcache = False#

Debug memcache usage. As well as printing debugging info to stdout, it also sends human-readable strings as memcached keys (that you can read by running memcached -vv as the server)

REZ_DEBUG_MEMCACHE#: The REZ_DEBUG_MEMCACHE environment variable can also be used to configure this.

debug_none = False#

Turn off all debugging messages. This overrides debug_all.

REZ_DEBUG_NONE#: The REZ_DEBUG_NONE environment variable can also be used to configure this.

debug_package_exclusions = False#

Print packages that are excluded from the resolve, and the filter rule responsible.

REZ_DEBUG_PACKAGE_EXCLUSIONS#: The REZ_DEBUG_PACKAGE_EXCLUSIONS environment variable can also be used to configure this.

debug_package_release = False#

Print debugging info such as VCS commands during package release. Note that rez-pip installations are controlled with this setting also.

REZ_DEBUG_PACKAGE_RELEASE#: The REZ_DEBUG_PACKAGE_RELEASE environment variable can also be used to configure this.

debug_plugins = False#

Print debugging info when loading plugins

REZ_DEBUG_PLUGINS#: The REZ_DEBUG_PLUGINS environment variable can also be used to configure this.

debug_resolve_memcache = False#

Print debugging info related to use of memcached during a resolve

REZ_DEBUG_RESOLVE_MEMCACHE#: The REZ_DEBUG_RESOLVE_MEMCACHE environment variable can also be used to configure this.

debug_resources = False#

Print debugging info when searching, loading and copying resources.

REZ_DEBUG_RESOURCES#: The REZ_DEBUG_RESOURCES environment variable can also be used to configure this.

shell_error_truncate_cap = 750#

Sets the maximum number of characters printed from the stdout / stderr of some shell commands when they fail. If 0, then the output is not truncated

REZ_SHELL_ERROR_TRUNCATE_CAP#: The REZ_SHELL_ERROR_TRUNCATE_CAP environment variable can also be used to configure this.

warn_all = False#

Turn on all warnings

REZ_WARN_ALL#: The REZ_WARN_ALL environment variable can also be used to configure this.

warn_none = False#

Turn off all warnings. This overrides warn_all.

REZ_WARN_NONE#: The REZ_WARN_NONE environment variable can also be used to configure this.

warn_shell_startup = False#

If true, print warnings associated with shell startup sequence, when using tools such as rez-env. For example, if the target shell type is sh, and the rcfile param is used, you would get a warning, because the sh shell does not support rcfile.

REZ_WARN_SHELL_STARTUP#: The REZ_WARN_SHELL_STARTUP environment variable can also be used to configure this.

warn_untimestamped = False#

If true, print a warning when an untimestamped package is found.

REZ_WARN_UNTIMESTAMPED#: The REZ_WARN_UNTIMESTAMPED environment variable can also be used to configure this.

Package Build/Release#

build_directory = "build"#

The default working directory for a package build, either absolute path or relative to the package source directory (this is typically where temporary build files are written).

REZ_BUILD_DIRECTORY#: The REZ_BUILD_DIRECTORY environment variable can also be used to configure this.

build_thread_count = "physical_cores"#

The number of threads a build system should use, eg the make -j option. If the string values logical_cores or physical_cores are used, it is set to the detected number of logical / physical cores on the host system. (Logical cores are the number of cores reported to the OS, physical are the number of actual hardware processor cores. They may differ if, ie, the CPUs support hyperthreading, in which case logical_cores == 2 * physical_cores). This setting is exposed as the environment variable REZ_BUILD_THREAD_COUNT during builds.

REZ_BUILD_THREAD_COUNT#: The REZ_BUILD_THREAD_COUNT environment variable can also be used to configure this.

make_package_temporarily_writable = True#

Sometimes a studio will run a post-release process to set a package and its payload to read-only. If you set this option to True, processes that mutate an existing package (such as releasing a variant into an existing package, or copying a package) will, if possible, temporarily make a package writable during these processes. The mode will be set back to original afterwards.

REZ_MAKE_PACKAGE_TEMPORARILY_WRITABLE#: The REZ_MAKE_PACKAGE_TEMPORARILY_WRITABLE environment variable can also be used to configure this.

prompt_release_message = False#

Prompt for release message using an editor. If set to False, there will be no editor prompt.

REZ_PROMPT_RELEASE_MESSAGE#: The REZ_PROMPT_RELEASE_MESSAGE environment variable can also be used to configure this.

release_hooks = []#

The release hooks to run when a release occurs. Release hooks are plugins. If a plugin listed here is not present, a warning message is printed. Note that a release hook plugin being loaded does not mean it will run. It needs to be listed here as well. Several built-in release hooks are available, see src/rezplugins/release_hook.

REZ_RELEASE_HOOKS#: The REZ_RELEASE_HOOKS environment variable can also be used to configure this.

use_variant_shortlinks = True#

Whether or not to use variant shortlinks when resolving variant root paths. You might want to disable this for testing purposes, but typically you would leave this True.

REZ_USE_VARIANT_SHORTLINKS#: The REZ_USE_VARIANT_SHORTLINKS environment variable can also be used to configure this.

variant_shortlinks_dirname = "_v"#

The subdirectory where hashed variant symlinks (known as variant shortlinks) are created. This is only relevant for packages whose ‘hashed_variants’ is set to True. To disable variant shortlinks, set this to None.

REZ_VARIANT_SHORTLINKS_DIRNAME#: The REZ_VARIANT_SHORTLINKS_DIRNAME environment variable can also be used to configure this.

Suites#

suite_alias_prefix_char = "+"#

The prefix character used to pass rez-specific command line arguments to alias scripts in a suite. This must be a character other than -, so that it doesn”t clash with the wrapped tools” own commandline arguments.

REZ_SUITE_ALIAS_PREFIX_CHAR#: The REZ_SUITE_ALIAS_PREFIX_CHAR environment variable can also be used to configure this.

Appearance#

browser = None#

The browser used to view documentation. The rez-help tool uses this On macOS, set this to open -a <your-app> if you want to use a specific app.

REZ_BROWSER#: The REZ_BROWSER environment variable can also be used to configure this.

difftool = None#

The viewer used to view file diffs. On macOS, set this to open -a <your-app> if you want to use a specific app.

REZ_DIFFTOOL#: The REZ_DIFFTOOL environment variable can also be used to configure this.

dot_image_format = "png"#

The default image format that dot-graphs are rendered to.

REZ_DOT_IMAGE_FORMAT#: The REZ_DOT_IMAGE_FORMAT environment variable can also be used to configure this.

editor = None#

The editor used to get user input in some cases. On macOS, set this to open -a <your-app> if you want to use a specific app.

REZ_EDITOR#: The REZ_EDITOR environment variable can also be used to configure this.

image_viewer = None#

The program used to view images by tools such as rez-context -g On macOS, set this to open -a <your-app> if you want to use a specific app.

REZ_IMAGE_VIEWER#: The REZ_IMAGE_VIEWER environment variable can also be used to configure this.

prefix_prompt = True#

If true, prefixes the prompt, suffixes if false. Ignored if set_prompt is false.

REZ_PREFIX_PROMPT#: The REZ_PREFIX_PROMPT environment variable can also be used to configure this.

quiet = False#

Suppress all extraneous output (warnings, debug messages, progress indicators and so on). Overrides all warn_xxx and debug_xxx settings.

REZ_QUIET#: The REZ_QUIET environment variable can also be used to configure this.

set_prompt = True#

If true, tools such as rez-env will update the prompt when moving into a new resolved shell. Prompt nerds might do fancy things with their prompt that Rez can’t deal with (but it can deal with a lot (colors etc) so try it first). By setting this to False, Rez will not change the prompt. Instead, you will probably want to set it yourself in your startup script (.bashrc etc). You will probably want to use the environment variable REZ_ENV_PROMPT, which contains the set of characters that are normally prefixed/suffixed to the prompt, ie >, >> etc.

REZ_SET_PROMPT#: The REZ_SET_PROMPT environment variable can also be used to configure this.

show_progress = True#

Show progress bars where applicable

REZ_SHOW_PROGRESS#: The REZ_SHOW_PROGRESS environment variable can also be used to configure this.

Misc#

create_executable_script_mode = "single"#

Default option on how to create scripts with create_executable_script(). In order to support both windows and other OS it is recommended to set this to both.

Possible modes:

single:
Creates the requested script only.
py:
Create .py script that will allow launching scripts on windows, if the shell adds .py to PATHEXT. Make sure to use PEP 397 py.exe as default application for .py files.
platform_specific:
Will create py script on windows and requested on other platforms
both:
Creates the requested file and a .py script so that scripts can be launched without extension from windows and other systems.

REZ_CREATE_EXECUTABLE_SCRIPT_MODE#: The REZ_CREATE_EXECUTABLE_SCRIPT_MODE environment variable can also be used to configure this.

max_package_changelog_chars = 65536#

If not zero, truncates all package changelog entries to this maximum length. You should set this value. Changelogs can theoretically be very large, and this adversely impacts package load times.

REZ_MAX_PACKAGE_CHANGELOG_CHARS#: The REZ_MAX_PACKAGE_CHANGELOG_CHARS environment variable can also be used to configure this.

max_package_changelog_revisions = 0#

If not zero, truncates all package changelogs to only show the last N commits

REZ_MAX_PACKAGE_CHANGELOG_REVISIONS#: The REZ_MAX_PACKAGE_CHANGELOG_REVISIONS environment variable can also be used to configure this.

optionvars = None#

A dict type config for storing arbitrary data that can be accessed by the optionvars() function in packages commands().

This is like user preferences for packages, which may not easy to define in package’s definition file directly due to the differences between machines/users/pipeline-roles.

Example:

# in your rezconfig.py
optionvars = {
    "userRoles": ["artist"]
}

And to access:

# in package.py
def commands():
    roles = optionvars("userRoles", default=None) or []
    if "artist" in roles:
        env.SOMETHING_FRIENDLY = "Yes"

Note that you can refer to values in nested dicts using dot notation:

def commands():
    if optionvars("nuke.lighting_tools_enabled"):
        ...

REZ_OPTIONVARS#: The REZ_OPTIONVARS environment variable can also be used to configure this.

pip_extra_args = []#

Configurable pip extra arguments passed to the rez-pip install command. Since the rez-pip install command already includes some pre-configured arguments (--target, --use-pep517) this setting can potentially override the default configuration in a way which can cause package installation issues. It is recommended to refrain from overriding the default arguments and only use this setting for additional arguments that might be needed. https://pip.pypa.io/en/stable/reference/pip_install/#options

REZ_PIP_EXTRA_ARGS#: The REZ_PIP_EXTRA_ARGS environment variable can also be used to configure this.

pip_install_remaps#

Default:

[
    # Typical bin copy behaviour
    # Path in record          | pip installed to    | copy to rez destination
    # ------------------------|---------------------|--------------------------
    # ../../bin/*             | bin/*               | bin/*
    {
        "record_path": r"^{p}{s}{p}{s}(bin{s}.*)",
        "pip_install": r"\1",
        "rez_install": r"\1",
    },
    # Fix for #821
    # Path in record          | pip installed to    | copy to rez destination
    # ------------------------|---------------------|--------------------------
    # ../../lib/python/*      | *                   | python/*
    {
        "record_path": r"^{p}{s}{p}{s}lib{s}python{s}(.*)",
        "pip_install": r"\1",
        "rez_install": r"python{s}\1",
    },
]

Substitutions for re.sub() when unknown parent paths are encountered in the pip package distribution record: name.dist-info/RECORD

Rez reads the distribution record to figure out where pip installed files to, then copies them to their final sub-path in the rez package. Ie, python source files are hard coded to be moved under the python sub-folder inside the rez package, which then gets added to PYTHONPATH upon rez-env.

When it can’t find the file listed in the record AND the path starts with a reference to the parent directory .., the following remaps are used to:

Match a path listed in the record to perform the filepath remapping;
re.sub() expression from step 1 to make the relative path of where pip actually installed the file to;
re.sub() expression from step 1 to make the destination filepath, relative to the rez variant root.

Use these tokens to avoid regular expression and OS-specific path issues:

“{pardir}” or “{p}” for parent directory: os.pardir, i.e. .. on Linux/Mac
“{sep}” or “{s}” for folder separators: os.sep, i.e. / on Linux/Mac

REZ_PIP_INSTALL_REMAPS#: The REZ_PIP_INSTALL_REMAPS environment variable can also be used to configure this.

Rez-1 Compatibility#

These settings are for rez v1 compatibility purposes.

debug_old_commands = False#

Print old commands and their converted rex equivalent. Note that this can cause very verbose output.

This currently has no effect.

Deprecated since version 2.114.0: Will be removed in a future version.

REZ_DEBUG_OLD_COMMANDS#: The REZ_DEBUG_OLD_COMMANDS environment variable can also be used to configure this.

disable_rez_1_compatibility = True#

If True, override all compatibility-related settings so that Rez-1 support is deprecated. This means that:

All warn/error settings in this section of the config will be set to warn=False, error=True;
rez_1_environment_variables will be set to False.

You should aim to do this. It will mean your packages are more strictly validated, and you can more easily use future versions of Rez.

Deprecated since version 2.114.0: Will be removed in a future release.

Changed in version 3.0.0: Changed the default value to True in preparation of future removal.

REZ_DISABLE_REZ_1_COMPATIBILITY#: The REZ_DISABLE_REZ_1_COMPATIBILITY environment variable can also be used to configure this.

error_old_commands = False#

See warn_old_commands.

Deprecated since version 2.114.0: Will be removed in a future release.

REZ_ERROR_OLD_COMMANDS#: The REZ_ERROR_OLD_COMMANDS environment variable can also be used to configure this.

rez_1_environment_variables = False#

If True, Rez will continue to generate the given environment variables in resolved environments, even though their use has been deprecated in Rez-2. The variables in question, and their Rez-2 equivalent (if any) are:

Deprecated since version 2.114.0: Will be removed in a future release.

Changed in version 3.0.0: Changed the default value to False in preparation of future removal.

REZ-1	REZ-2
REZ_REQUEST	`REZ_USED_REQUEST`
REZ_RESOLVE	`REZ_USED_RESOLVE`
REZ_VERSION	`REZ_USED_VERSION`
REZ_PATH	`REZ_USED`
REZ_RESOLVE_MODE	not set
REZ_RAW_REQUEST	not set
REZ_IN_REZ_RELEASE	not set

REZ_REZ_1_ENVIRONMENT_VARIABLES#: The REZ_REZ_1_ENVIRONMENT_VARIABLES environment variable can also be used to configure this.

warn_old_commands = True#

Warn or disallow when a package is found to contain old rez-1-style commands.

Deprecated since version 2.114.0: Will be removed in a future release.

REZ_WARN_OLD_COMMANDS#: The REZ_WARN_OLD_COMMANDS environment variable can also be used to configure this.

Help#

documentation_url = "https://rez.readthedocs.io"#

Where Rez’s own documentation is hosted

REZ_DOCUMENTATION_URL#: The REZ_DOCUMENTATION_URL environment variable can also be used to configure this.

Colorization#

The following settings provide styling information for output to the console, and is based on the capabilities of the Colorama module (https://pypi.python.org/pypi/colorama).

*_fore and *_back colors are based on the colors supported by this module and the console. One or more styles can be applied using the *_styles configuration. These settings will also affect the logger used by rez.

At the time of writing, valid values are: fore/back: black, red, green, yellow, blue, magenta, cyan, white style: dim, normal, bright

color_enabled = "posix")#

Enables/disables colorization globally.

Warning

Turned off for Windows currently as there seems to be a problem with the colorama module.

May also set to the string force, which will make rez output color styling information, even if the the output streams are not ttys. Useful if you are piping the output of rez, but will eventually be printing to a tty later. When force is used, will generally be set through an environment variable, eg:

echo $(REZ_COLOR_ENABLED=force python -c "from rez.utils.colorize import Printer, local; Printer()('foo', local)")

TODO: Colorama is documented to work on Windows and trivial test case proves this to be the case, but it doesn’t work in Rez (with cmd.exe). If the initialise is called in src/rez/__init__.py then it does work, however this is not always desirable. As it does with with some Windows shells it can be enabled in rezconfig

REZ_COLOR_ENABLED#: The REZ_COLOR_ENABLED environment variable can also be used to configure this.