Getting Started


  • Python 3.6 or higher. Python 2 is not supported.

  • The required Python packages are the following:

argcomplete==3.1.2; python_version < '3.8'
argcomplete==3.1.6; python_version >= '3.8'
importlib_metadata==4.0.1; python_version < '3.8'
pytest-forked==1.4.0; python_version == '3.6'
pytest-forked==1.6.0; python_version >= '3.7'
pytest-rerunfailures==10.3; python_version == '3.6'
pytest-rerunfailures==13.0; python_version >= '3.7'
requests==2.27.1; python_version == '3.6'
requests==2.31.0; python_version >= '3.7'
semver==2.13.0; python_version == '3.6'
semver==3.0.2; python_version >= '3.7'
setuptools==59.6.0; python_version == '3.6'
setuptools==68.0.0; python_version == '3.7'
setuptools==69.0.2; python_version >= '3.8'


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


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

Getting the Framework

Stable ReFrame releases are available through different channels.


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.


ReFrame is available as an EasyBuild package:

eb ReFrame-VERSION.eb -r

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


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.


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

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

The VERSION_TAG is the version number prefixed by v, e.g., v3.5.0. The ./ 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 ./ has two additional variant options:

  • +docs: This will also build the documentation.

  • +pygelf: This will install the bindings for handling Graylog log messages.


New 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.

Enabling auto-completion

New 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.


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 first tutorial Tutorial 1: Getting Started with ReFrame, which will guide you step-by-step in both writing your first tests and in configuring ReFrame. The rest of the tutorials explore additional capabilities of the framework and cover several topics that you will likely come across when writing your own tests.

The Configuring ReFrame for Your Site page provides more details on how a configuration file is structured and the Advanced Topics explain some more advanced concepts as well as some implementation details. The ReFrame Manuals provide complete reference guides for the command line interface, the configuration parameters and the programming APIs for writing tests.

Finally, if you are not new to ReFrame and you have been using the 3.x versions, 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.