============ Installation ============ Installation Script =================== To install rez, you will need: 1. Python 3.8 or above. We support 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13. The python interpreter you use to run the install script will be the interpreter used by rez itself. 2. The source code. You can get it by either cloning the `repository `_ with git or downloading it from the `latest release `_. If you download rez from the release page on GitHub, don't forget to unpack the downloaded archive. Then from the root directory, run:: ]$ python ./install.py This installs rez to ``/opt/rez``. Use ``install.py -h`` to see the different install options. Once the installation is complete, a message tells you how to run it:: SUCCESS! To activate Rez, add the following path to $PATH: /opt/rez/bin/rez You may also want to source the completion script (for bash): source /opt/rez/completion/complete.sh .. warning:: Do **not** move the installation. Re-install to a new location if you want to change the install path. If you want to install rez for multiple operating systems, perform separate installs for each of those systems. Installation via pip ==================== It is possible to install rez with pip, like so:: ]$ pip install rez However, this comes with a caveat. Rez command line tools **are not guaranteed to work correctly** once inside a rez environment (ie after using the :ref:`rez-env` command). The reasons are given in the next section. Pip installation is adequate however, if all you require is the rez API, or you don't require its command line tools to be available within a resolved environment. .. note:: that running pip-installed rez command line tools will print a warning like so: .. code-block:: text Pip-based rez installation detected. Please be aware that rez command line tools are not guaranteed to function correctly in this case. See :ref:`why-not-pip-for-production` for further details. .. _verifying-release-artifacts: Verifying release artifacts =========================== Starting with rez 3.4.0, every released artifact has a `SLSA `_ and `PyPI Publish `_ attestations, signed using `Sigstore `_. Two kinds of attestations are produced: * **SLSA build provenance attestations** generated by the `actions/attest `_ action. These are attached to every artifact (sdist, wheel and the git archives). * **PyPI Trusted Publisher attestations** generated by `pypa/gh-action-pypi-publish `_ when the sdist and wheel are uploaded to PyPI. Both the SLSA and the PyPI Publish attestations are uploaded to PyPI. Verify artifacts downloaded from GitHub --------------------------------------- The sdist, wheel and the git source archives published on the `GitHub releases page `_ are accompanied by a ``*.sigstore.json`` file containing the SLSA attestation bundle. They can be verified with the `GitHub CLI `_. For example, to verify the ``rez-3.4.0.tar.gz`` artifact, you can run:: ]$ gh attestation verify rez-3.4.0.tar.gz \ --repo AcademySoftwareFoundation/rez \ --signer-workflow AcademySoftwareFoundation/rez/.github/workflows/pypi.yaml \ --source-ref refs/tags/3.4.0 \ --deny-self-hosted-runners The ``gh`` CLI will automatically discover the matching attestation, either from the local ``*.sigstore.json`` bundle next to the file or from the `GitHub attestations API `_. If you want to be even stricter, you can pin the exact source commit with ``--source-digest ``, or replace ``--signer-workflow`` with ``--cert-identity https://github.com/AcademySoftwareFoundation/rez/.github/workflows/pypi.yaml@refs/tags/3.4.0`` to require an exact match on the signer's Subject Alternative Name (which includes the ref the workflow ran from). Artifacts downloaded from PyPI ------------------------------ The sdist and wheel uploaded to `PyPI `_ ship with PyPI attestations. The simplest way to verify them is to install `pypi-attestations `_ and use its ``verify pypi`` command, which fetches the artifact and its provenance from PyPI and validates them against the expected publisher identity:: ]$ pip install pypi-attestations ]$ pypi-attestations verify pypi \ --repository https://github.com/AcademySoftwareFoundation/rez \ pypi:rez-3.4.0-py3-none-any.whl .. _why-not-pip-for-production: Why Not Pip For Production? =========================== Rez is not a normal python package. Although it can successfully be installed using standard mechanisms such as pip, this comes with a number of caveats. Specifically: * When within a rez environment (ie after using the :ref:`rez-env` command), the rez command line tools are not guaranteed to function correctly; * When within a rez environment, other packages' tools (that were also installed with pip) remain visible, but are not guaranteed to work. When you enter a rez environment, the rez packages in the resolve configure that environment as they see fit. For example, it is not uncommon for a python package to append to :envvar:`PYTHONPATH`. Environment variables such as :envvar:`PYTHONPATH` affect the behaviour of tools, including rez itself, and this can cause it to crash or behave abnormally. When you use the ``install.py`` script to install rez, some extra steps are taken to avoid this problem. Specifically: * Rez is installed into a virtualenv so that it operates standalone; * The rez tools are shebanged with ``python -E``, in order to protect them from environment variables that affect python's behaviour; * The rez tools are stored in their own directory, so that other unrelated tools are not visible. Due to the way standard wheel-based python installations work, it simply is not possible to perform these extra steps without using a custom installation script. Wheels do not give the opportunity to run post-installation code. Neither do they provide functionality for specifying interpreter arguments to be added for any given entry point.