Getting Started

Requirements

Python 3.6 or higher. Python 2 is not supported.
The required Python packages are the following:

archspec==0.2.5 argcomplete==3.1.2; python_version < '3.8' argcomplete==3.6.3; python_version >= '3.8' ClusterShell==1.9.3 fasteners==0.19; python_version < '3.10' fasteners==0.20; python_version >= '3.10' importlib_metadata==4.0.1; python_version < '3.8' jinja2==3.0.3; python_version == '3.6' jinja2==3.1.6; python_version >= '3.7' jsonschema==3.2.0 lxml==5.2.0; python_version < '3.8' and platform_machine == 'aarch64' lxml==5.4.0; python_version < '3.8' and platform_machine != 'aarch64' lxml==6.0.2; python_version >= '3.8' pytest==7.0.1; python_version < '3.8' pytest==8.3.5; python_version == '3.8' pytest==8.4.2; python_version >= '3.9' pytest-forked==1.4.0; python_version == '3.6' pytest-forked==1.6.0; python_version >= '3.7' pytest-parallel==0.1.1 pytest-rerunfailures==10.3; python_version == '3.6' pytest-rerunfailures==13.0; python_version == '3.7' pytest-rerunfailures==14.0; python_version == '3.8' pytest-rerunfailures==16.0.1; python_version == '3.9' pytest-rerunfailures==16.1; python_version >= '3.10' PyYAML==6.0.1; python_version < '3.8' PyYAML==6.0.3; python_version >= '3.8' requests==2.27.1; python_version == '3.6' requests==2.31.0; python_version == '3.7' requests==2.32.4; python_version >= '3.8' semver==2.13.0; python_version == '3.6' semver==3.0.4; python_version >= '3.7' setuptools==59.6.0; python_version == '3.6' setuptools==68.0.0; python_version == '3.7' setuptools==75.3.0; python_version == '3.8' setuptools==80.9.0; python_version >= '3.9' tabulate==0.8.10; python_version == '3.6' tabulate==0.9.0; python_version >= '3.7' wcwidth==0.2.14 

Note

Changed in version 3.0: Support for Python 3.5 has been dropped.

Warning

Although ReFrame supports Python 3.6 and 3.7, you should note that these Python versions have reached end-of-life and you are strongly advised to use a newer version. ReFrame installations on these Python versions may use out-of-date dependencies due to incompatibilities.

Getting the Framework

Stable ReFrame releases are available through different channels.

Spack

ReFrame is available as a Spack package:

spack install reframe

There are the following variants available:

+docs: This will install the man pages of ReFrame.
+gelf: This will install the bindings for handling Graylog log messages.

EasyBuild

ReFrame is available as an EasyBuild package:

eb ReFrame-VERSION.eb -r

This will install the man pages as well as the Graylog bindings.

PyPI

ReFrame is available as a PyPI package:

pip install reframe-hpc

This is a bare installation of the framework. It will not install the documentation, the tutorial examples or the bindings for handling Graylog log messages.

Github

Any ReFrame version can be very easily installed directly from Github:

pushd /path/to/install/prefix git clone -q --depth 1 --branch VERSION_TAG https://github.com/reframe-hpc/reframe.git pushd reframe && ./bootstrap.sh && popd export PATH=$(pwd)/bin:$PATH popd 

The VERSION_TAG is the version number prefixed by v, e.g., v3.5.0. The ./bootstrap.sh script will fetch ReFrame’s requirements under its installation prefix. It will not set the PYTHONPATH, so it will not affect the user’s Python installation. The ./bootstrap.sh has two additional variant options:

+docs: This will also build the documentation.
+pygelf: This will install the bindings for handling Graylog log messages.

Note

Added in version 3.1: The bootstrap script for ReFrame was added. For previous ReFrame versions you should install its requirements using pip install -r requirements.txt in a Python virtual environment.

Changed in version 4.5: ReFrame now supports multiarch builds and it will place all of its dependencies in an arch-specific directory under its prefix. Also, pip is no more required, as the bootstrap script will start a virtual environment without pip and will fetch a fresh pip, which will be used to install the dependencies.

Enabling auto-completion

Added in version 3.4.1.

You can enable auto-completion for ReFrame by sourcing in your shell the corresponding script in <install_prefix>/share/completions/reframe.<shell>. Auto-completion is supported for Bash, Tcsh and Fish shells.

Note

Changed in version 3.4.2: The shell completion scripts have been moved under share/completions/.

Where to Go from Here

If you are new to ReFrame, the place to start is the ReFrame Tutorial, which will guide you through all the concepts of the framework and get you up and running. If you are looking for a particular topic that is not covered in the tutorial, you can refer to the ReFrame How Tos or the Advanced Topics. For detailed reference guides for the command line, the configuration and the programming API, refer to the ReFrame Manuals.

Finally, if you are already a user of ReFrame 3.x version, you should read the What’s New in ReFrame 4.0 page, which explains what are the key new features of ReFrame 4.0 as well as all the breaking changes.