rez-windows-platform

Running rez on Windows — why only cmd, gitbash, powershell and pwsh are registered there and how the default is picked, the path-separator trap where cmd and pwsh join with ';' while gitbash joins with ':', backslash versus forward slash in generated shell code, the 260-character MAX_PATH limit and why variant install paths exceed it, the platform/arch/os implicit packages, using rez-interpret as a cross-shell oracle without launching a shell, install and config-file layout, and CI differences. Use when a package or resolve behaves differently on Windows, when porting a package across operating systems, when a deep path fails to read or write, or when a one-liner works in bash and fails in cmd. Covers Rez 3.4.0.

Rez on Windows

One-sentence summary: on Windows rez registers only cmd, gitbash, powershell and pwsh as shells, and those shells disagree about the path separator — cmd and pwsh join lists with ; while gitbash joins them with : — which is why the same package.py can produce a working PATH in one shell and a broken one in another.

Skill scope: the Windows-specific differences. For the commands() body and the rex API in general see rez-package-commands; for package.py attributes see rez-package-definition; for config layering and plugin discovery see rez-config-plugins; for a resolve that fails on any platform see rez-resolve-troubleshooting.

Platform note. Every fenced block in this skill is tagged with the shell it belongs to (powershell, bat, ```bash). Commands tagged powershell or bat are Windows-only and will fail on Linux or macOS, where those shells are not registered. The rez-interpret examples are safe to run anywhere — it only prints text, never launches a shell.

Which shells exist on Windows

Rez ships shell plugins for bash, sh, csh, tcsh, zsh, cmd, gitbash, powershell and pwsh, but only the ones valid for the current platform are registered. On Windows:

text

cmd, gitbash, powershell, pwsh

The POSIX shells are not registered there, so rez-env --shell bash is not a valid value on Windows and vice versa. Ask rez rather than assuming, because the answer is platform-dependent:

python

from rez.shells import get_shell_types

print(get_shell_types())   # ['cmd', 'gitbash', 'powershell', 'pwsh'] on Windows

How the default shell is chosen

The order is default_shell, then system.shell:

bash

rez-config default_shell

default_shell is empty ('') out of the box, in which case rez falls back to detecting the current shell — on Windows that is typically powershell. There is no default_windows_shell setting in rez 3.4.0; default_shell is the only knob, and it applies on every platform.

To target a shell for one invocation:

powershell

# Windows only — 'cmd' is not a registered shell on Linux or macOS
rez-env foo --shell cmd

bat

REM Windows only
rez-env foo --shell cmd

The path separator trap

This is the difference that breaks real packages. The same rex produces different text per shell:

bash

rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f cmd --pv MY_PATH
rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f pwsh --pv MY_PATH
rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f gitbash --pv MY_PATH

With MY_PATH already set, the generated code is:

Shell	Generated line	Separator
cmd	set MY_PATH=C:\pkgs\foo\bin;C:\Program Files\Git\usr\bin;...	;
pwsh	Set-Item -Path "Env:MY_PATH" -Value ("C:\pkgs\foo\bin;" + ...)	;
gitbash	export MY_PATH="C:/pkgs/foo/bin:${MY_PATH}"	:

Two things to take from it:

• The list separator is ; under cmd and pwsh, and : under gitbash. A package.py that builds a list by hand — joining with : because it was written on Linux — produces a single unreadable entry on Windows. Use the rex list operations (append, prepend, set) and let rez pick the separator.
• cmd and pwsh emit backslashes; gitbash keeps forward slashes. Both work in their own shell, so the difference only bites when you compare or string-match paths.

The separator applies to every list-valued variable, not just PATH — PYTHONPATH, LD_LIBRARY_PATH-style variables and any custom list behave the same way.

Backslashes, drive letters and path separators

• os.sep is a backslash and os.pathsep is a semicolon on Windows, versus a forward slash and a colon on POSIX.
• packages_path is a Python list, so it is immune to the separator problem — do not build a ;-joined string for it.
• Flags that do take a joined path list use os.pathsep, so they take ; on Windows. This includes rez-env --paths and rez-search --paths:

powershell

# Windows only — the separator is ';' here, not ':'
rez-env --paths "C:/studio/packages;C:/studio/local" foo -o context.rxt

• Paths inside a package.py should be written with forward slashes or with {root}, and joined with the rex API. A hard-coded backslash will not survive a move to Linux, and a hard-coded colon will not survive a move to Windows.

Path length: the 260-character limit

Win32 caps a path at 260 characters (MAX_PATH) unless long paths are enabled. Rez paths are deep by construction, so this is a real failure mode and not a theoretical one.

The depth comes from how a variant is laid out. For the filesystem repository the install path is <repo>/<name>/<version>/<variant subpath>/, and the variant subpath nests one directory per variant requirement. A package with variants = [["python-3.11", "pytest-7", "six"]] installs under:

text

python-3.11\pytest-7\six

Add a deep shared-storage root, a build directory during rez-build, and the package's own internal tree, and the total passes 260 long before the layout looks unreasonable. A realistic studio example — a UNC share, a long show name, an eight-requirement variant and a nested Python package — measures 316 characters, 56 over the limit.

Rez 3.4.0 has a helper for this, rez.utils.filesystem.windows_long_path(), which prefixes the extended-length marker to lift the limit.

text

\\?\C:\pkgs\foo          # local path
\\?\UNC\server\share\x    # UNC path

It is applied internally and selectively — notably in the retry path of robust_rmtree — so do not assume it covers the operation that just failed for you. Most user-facing operations still go through ordinary paths.

To enable long paths system-wide on Windows 10 1607 and later, set the registry value LongPathsEnabled to 1 under HKLM\SYSTEM\CurrentControlSet\Control\FileSystem, or apply the equivalent Group Policy ("Enable Win32 long paths"). A reboot is required. The extended-length prefix itself only works on absolute paths with no forward slashes and no . or .. components, which is why rez applies it to os.path.abspath() output rather than to the path as written.

Telling a length problem from a separator problem

Both surface as "rez cannot find or write this path", and they are easy to confuse. Two cheap ways to separate them:

• Length: the failure tracks the path's depth, not its content. Shortening the repository root or the package name makes it disappear. Measure it directly — python -c "import os; print(len(os.path.abspath(<path>)))" — and compare against 260.
• Separator: the failure tracks content, not depth. A list variable arrives as one long entry, or a path with the wrong slashes. The same path at the same length works in another shell.

If the path is under 260 and still fails, it is not the length limit — go back to the separator and quoting sections above.

Where to shorten

When you cannot enable long paths fleet-wide, the cheapest wins are, in order:

1. Move the package repository to a shallower root (C:\packages beats a deep UNC share).
2. Shorten the package name — it appears in every variant path.
3. Reduce the number of variant requirements, or let rez shortlink them.
4. Avoid long version strings; 1.14.3+local.2026.10.05 costs more than 1.14.3.

The platform implicit packages

Windows resolves add implicit packages that carry the OS identity. On a Windows 11 machine:

bash

rez-config implicit_packages

text

- ~platform==windows
- ~arch==AMD64
- ~os==windows-10.0.26100.SP0

Three consequences:

1. Any variant that must differ per OS keys off platform or os, not off sys.platform at module scope — see rez-package-pitfalls for why module scope is evaluated on the build machine.
2. The os version string is a moving target: a Windows feature update changes ~os, so a variant pinned to an exact os version stops resolving after an upgrade. Prefer platform.
3. platform_map (default {}) can normalise a platform name across machines when a fleet reports slightly different values.

rez-interpret: the cross-shell oracle

rez-interpret executes rex and prints the resulting shell code for any registered shell. It never launches one, which makes it the cheapest way to answer "what will this actually do on cmd?" — including on a Linux build machine that has no cmd at all.

bash

rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f cmd
rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f pwsh
rez-interpret --no-env -c 'env.FOO = "bar"' -f cmd

-f accepts cmd, gitbash, powershell, pwsh, plus dict and table for a shell-independent view. --pv marks variables that should be updated rather than overwritten on first reference — without it, a prepend against a variable rez cannot see looks like a plain overwrite, which is the most common way to misread this output.

Use it when reviewing a package.py for cross-platform behaviour, and when a one-liner works in bash but not in cmd.

Install and config layout

Rez is installed into the Python it was pip-installed into, so on Windows the entry points land in that interpreter's Scripts directory rather than a bin directory. Confirm which rez you are running and where its config comes from:

bash

rez-status
rez-config --source-list packages_path

--source-list prints the config files rez actually read, in order, with real paths. On Windows those are drive-lettered paths such as C:\Users\<user>\AppData\Local\Programs\Python\Python312\Lib\site-packages\rez\rezconfig.py. It is the fastest way to prove a setting is coming from the file you think it is.

CI differences

• Rez needs the Python it was installed into on PATH. On Windows hosted runners, prefer actions/setup-python and install rez into it, so the Scripts directory is already on PATH.
• Build and test steps are the same commands — rez-build --install, then rez-test — but the shell the runner uses to invoke them differs, which changes quoting. A request with a range (rez-env 'foo<2') needs single quotes under bash and gitbash, and double quotes under cmd.
• Package tests that shell out should not assume a POSIX shell. See rez-test-ci for wiring tests into CI.
• rez-benchmark timings are not comparable across operating systems; compare Windows to Windows.

Troubleshooting

Symptom	Cause
rez-env --shell bash rejected	bash is not registered on Windows; use cmd, gitbash, powershell or pwsh
A list variable arrives as one long entry	joined with : on a shell that expects ; (or the reverse)
PATH grew instead of prepending	compared without --pv; the parent value rez cannot see looks like it was overwritten
A one-liner works in bash, fails in cmd	quoting differs — single quotes are not quoting in cmd
Variant stops resolving after a Windows update	the variant pins an exact ~os version; prefer platform
Rez is not found in CI	the install's Scripts directory is not on PATH
Paths have the wrong slashes	cmd/pwsh emit backslashes, gitbash emits forward slashes; both are correct for their shell
A path fails only when deeply nested	over the 260-character MAX_PATH limit; measure it and shorten the root or the package name
A failure survives enabling long paths	probably not length — check separators and quoting instead
A package works when built on Windows only	a module-scope value was frozen on the build machine — see rez-package-pitfalls

Agent workflow

1. Establish the platform's registered shells from rez itself (get_shell_types), not from memory.
2. Check rez-config default_shell — empty means detection picked powershell on Windows.
3. For any list-valued environment variable, use rex append/prepend so the separator is chosen per shell; never hand-join with : or ;.
4. Verify generated code with rez-interpret -f <shell> --pv <VAR> for each shell you must support.
5. Prefer platform over an exact os version when a variant needs to differ per OS.
6. When a path operation fails, measure the path length before changing anything else — over 260 characters is a length problem, under it is a separator or quoting problem.
7. Use rez-config --source-list <setting> to prove which config file a value came from.