Rez pip integration

One-sentence summary: rez-pip runs pip install inside a rezified python and converts the result — plus the dependencies it had to install — into rez packages, and it only goes one way: pip to rez, never rez to pip.

Skill scope: getting PyPI packages into rez. For authoring a package.py by hand see rez-package-authoring; for the resolve that consumes the result see rez-resolve; for driving the conversion from Python see rez-python-api.

What rez-pip does

Rez is language agnostic, but python is everywhere, so rez knows how to translate a pip package into a rez package. The conversion:

• downloads and installs the package with pip, inside a rez python package;
• writes a rez package for it, plus a rez package for each dependency pip had to install;
• gives each generated package a dependency on python-MAJOR.MINOR.

It does not do the reverse. There is no rez-to-pip converter, and upstream documents a rewrite of rez-pip as a plugin to address most of its current limitations.

Choosing the python version

This is the decision everything else follows from, so make it first and make it explicit:

rez-pip --install requests --python-version 3.11

--python-version names a rez python package version. rez resolves it, runs that interpreter's pip, and the generated packages depend on python-3.11. Leave it out and you get the latest python rez package, which is rarely what a studio wants.

If a package is not pure python — it ships a .so or a .pyd — it is built against one interpreter, so run rez-pip once per python version you need. One conversion does not serve several pythons.

Install, release, or a custom prefix

rez-pip --install foo                 # local_packages_path
rez-pip --install --release foo       # release_packages_path
rez-pip --install --prefix /studio/packages/int foo

Check where those actually point before you predict where a package will land:

rez-config local_packages_path
rez-config release_packages_path

--install is required; rez-pip without it errors out with Expected one of: --install. That is deliberate — a conversion you did not ask to persist should not write into a package repository.

Which pip runs

pip is too tightly coupled to the interpreter it ships with for rez to treat it as a normal dependency, so rez-pip walks a fallback chain and prints what it picked:

1. pip inside the rezified python package named by --python-version (or the latest);
2. if that has none, pip inside a rezified pip package (backwards compatibility);
3. otherwise, the pip in rez's own virtualenv.

Whichever it lands on, pip must be 19.0 or newer — that is a hard requirement.

Two consequences worth internalising:

• --pip-version does not exist. It was removed, because a pip version decoupled from an interpreter cannot be honoured.
• Install pip into your python packages rather than as its own rez package. Build python 2 with --with-ensurepip and upgrade it; python 3 already ships one, but check the version. Add wheel and refresh setuptools while you are there.

When installing into an interpreter by hand, make sure it lands in that interpreter:

/path/to/python -E -s -m pip install foo

-E ignores PYTHON* environment variables and -s takes your user site out of the equation.

Flags

-e / --extra takes everything after it, so it must be last. Anything you put there replaces rez's pre-configured pip arguments rather than adding to them.

Verifying a conversion

rez-search foo
rez-env foo -o context.rxt
rez-context context.rxt --so

rez-search proves the packages exist in a repository on your search path; the rez-env / rez-context pair proves they actually resolve and shows you which python came along. Do both — a conversion that wrote a package nobody can resolve is the common failure, not the rare one.

The API

from rez.pip import pip_install_package, InstallMode

installed, skipped = pip_install_package(
    "foo",
    python_version="3.11",
    release=False,
    prefix=None,
    extra_args=None,
    mode=InstallMode.min_deps,
)

It returns a 2-tuple of Variant lists: what was installed, and what was skipped because an existing rez package already satisfied it. InstallMode has two members:

The signature also still carries pip_version, but the CLI no longer passes it and --pip-version was removed — treat it as legacy.

Troubleshooting

Agent workflow

1. Decide the target python version first, and always pass --python-version.
2. Confirm the destination with rez-config local_packages_path and rez-config release_packages_path before you convert.
3. Convert with --install, adding --release or --prefix only when you mean it.
4. Verify with rez-search and a real rez-env resolve — existence is not resolvability.
5. For a non-pure package, repeat the conversion for every python version that needs it.
6. Reserve -e for a one-off pip workaround; a conversion that needs custom pip flags is a candidate for a hand-written package.py instead.