rez-package-orderers

How rez decides which version of a package to pick — the package_orderers setting, the five built-in orderers sorted / version_split / per_family / soft_timestamp / no_order, how orderers apply to variants as well as packages, writing and registering a custom orderer, and how to prove an orderer is or is not what changed your resolve. Use when rez picks a version you did not expect and the resolve is not failing, or when a studio needs python-2-style version pinning to survive an upgrade. Covers Rez 3.4.0.

One-sentence summary: an orderer reorders the version list rez sorts before it solves, so the "latest" version rez returns is the latest by the orderer's rule — and a configured orderer is the only reason a successful resolve picks an older version without any conflict to explain it.

Skill scope: the orderer mechanism itself — which orderers exist, how they are configured, and how to tell whether one is in play. For how version tokens compare (1.0.0 vs 1.0.0-beta, alphanumeric vs numeric segments) see rez-core-concepts; for a resolve that fails see rez-resolve-troubleshooting, since orderers only matter when the resolve succeeds; for reading the solver trace see rez-resolve.

What an orderer changes

The solver always asks the package repository for versions in a defined order and takes the first that fits. Orderers change that order. They do not forbid anything: a higher version is still reachable if you request it explicitly.

That is the diagnostic signature. If rez-env foo gives you 1.1.0 while rez-env foo-2 happily gives you 2.0.0, and there is no conflict anywhere, an orderer is almost always why.

Orderers apply to variants as well as to package versions, so a variant list is reordered the same way.

Is an orderer in play?

Check before you theorise — the default is empty:

bash

rez-config package_orderers

An empty list means no orderer is configured and the default (sorted, descending) applies. A non-empty list is inherited through the normal config layering, so also confirm where it came from:

bash

rez-config --source-list package_orderers

The built-in orderers

type	What it does
sorted	the default — sort by version, descending
version_split	versions less than or equal to first_version first, then the default order
per_family	apply different orderers to different package families
soft_timestamp	versions released before timestamp first, then the rest; rank relaxes it
no_order	a no-op — explicitly leave a package's order alone

sorted

The default. You only need to name it to change its direction, or to scope it:

python

package_orderers = [
    {
        "type": "sorted",        # required
        "descending": True,      # required
        "packages": ["python"],  # optional; omit to apply to every package
    }
]

descending: False inverts it, so the lowest version wins. Verified against a repository holding foo-1.0.0, foo-1.1.0, foo-2.0.0:

Orderer	rez-env foo resolves
none (default)	foo-2.0.0
sorted with descending: False	foo-1.0.0

version_split

Orders every version less than or equal to first_version first, then falls back to the default order for the rest. Given [5, 4, 3, 2, 1], an orderer with first_version=3 yields [3, 2, 1, 5, 4].

python

package_orderers = [
    {
        "type": "version_split",
        "first_version": "1.1.0",
    }
]

With the same three foo versions, first_version: "1.1.0" makes rez-env foo resolve foo-1.1.0 instead of foo-2.0.0. Note the comparison is less than or equal to, so the named version itself is included in the preferred group.

The canonical studio use is easing a python-2 to python-3 migration:

python

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

For the python family, versions at or below 2.7.16 win. An explicit rez-env python-3 still gets 3.7.4.

per_family

Applies different orderers to different families. Any orderer above can be nested in it, together with a packages list. A family not named by any nested orderer keeps the default order.

This is also how you scope no_order.

soft_timestamp

Prefers packages released before timestamp (a Unix epoch integer), in descending order, followed by everything released after. rank relaxes the boundary: a non-zero rank lets version changes at that rank and above win over the timestamp.

python

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

rank: 3 is the usual choice under semantic versioning — it allows a different patch number through. Generate the timestamp rather than hand-computing it:

bash

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

Which version wins depends on rank, and the effect is not monotonic — a rank that lets a later patch through can land on a different version than a rank that lets a later minor through. Measure it against your own repository rather than assuming, because the answer depends on when each version was actually released.

no_order

A no-op. It exists so that inside a per_family block you can apply an orderer broadly but exempt one package:

python

package_orderers = [
    {
        "type": "per_family",
        "orderers": [
            {"packages": ["foo"], "type": "no_order"},
        ],
    }
]

Custom orderers

Subclass PackageOrder, implement the mandatory methods, and register it with register_orderer. Everything except sort_key_implementation is boilerplate you must supply for serialization:

python

# rezconfig.py
from rez.package_order import PackageOrder, register_orderer


class MyOrderer(PackageOrder):
    name = "my_orderer"

    def __init__(self, custom_arg, **kwargs):
        super().__init__(**kwargs)
        self.custom_arg = custom_arg

    def sort_key_implementation(self, package_name, version):
        ...

    def __str__(self):
        ...

    def __eq__(self, other):
        ...

    def to_pod(self, other):
        ...

    @classmethod
    def from_pod(cls, data):
        ...


register_orderer(MyOrderer)

package_orderers = [
    {
        "type": "my_orderer",
        "custom_arg": "value here",
    }
]

rezconfig.py is ordinary Python, so the class is defined and registered at config load time.

Do not pass self to super().__init__() — super().__init__(self, **kwargs) raises TypeError: 'MyOrderer' object is not iterable, because self lands in the packages argument that the base class sorts. The upstream package_orderers.rst at 3.4.0 shows the broken form in its custom-orderer example; the correct call is super().__init__(**kwargs).

Upstream explicitly warns against this: a custom orderer makes environments behave in ways users do not expect, and makes the affected packages harder to share. Prefer a built-in, and prefer version_split over anything bespoke.

Verifying what an orderer did

Never infer the effect from one command — compare the resolve against the version list.

bash

rez-search foo                    # every version, as the repository holds them
rez-env foo -o context.rxt        # what the solver actually picked
rez-context --so                  # the resolved version, with the request that produced it

If rez-context --so shows the version you did not expect, and rez-search shows a newer one exists, the orderer is the explanation. Confirm by repeating the resolve with the setting emptied — package_orderers is a normal config key, so a temporary override is enough to prove it.

Troubleshooting

Symptom	Cause
An older version wins with no conflict	an orderer reordered the version list
rez-env foo and rez-env foo-2 disagree	working as intended — orderers do not forbid explicit requests
no_order seems to do nothing	that is what it does; it only matters inside per_family
An unknown type is rejected at resolve time	only sorted, version_split, per_family, soft_timestamp, no_order and registered custom names are accepted
The orderer applies to packages I did not name	omit packages (outside per_family) and it applies to everything
A variant is chosen oddly	orderers apply to variants too, not just versions
soft_timestamp picks a surprising version	rank decides how far past the timestamp a version may drift; check it

Agent workflow

1. Read rez-config package_orderers first — an empty list means orderers are not your problem.
2. Find where a non-empty value comes from with rez-config --source-list package_orderers.
3. Distinguish "the version list is ordered unexpectedly" (rez-search) from "the solve failed" — the latter is rez-resolve-troubleshooting, not this skill.
4. Prefer version_split and per_family over a custom orderer; scope with packages.
5. Verify by resolving and inspecting with rez-context --so, then repeat with the orderer removed to prove it is the cause.