Installation and setup

Ubuntu, Fedora & SUSE/openSUSE

First, clone the git repository:

git clone

Next, run the bootstrap script, which will do everything for you assuming you have sudo:

cd teuthology

Finally, activate the virtualenv:

source virtualenv/bin/activate

Run a teuthology command to confirm that everything’s working. For instance:

teuthology --help


The bootstrap script was recently updated to support MacOS X using homebrew:


Note: Certain features might not work properly on MacOS X. Patches are encouraged, but it has never been a goal of ours to run a full teuthology setup on a Mac.

Other operating systems

Patches are welcomed to add bootstrap support for other operating systems. Until then, manual installs are possible

First install the non-PyPI dependencies:

python-dev python-pip python-virtualenv libevent-dev python-libvirt

Next, clone its git repository, create a virtualenv, and install dependencies. The instructions are given below:

git clone
cd teuthology
virtualenv --python python3 ./virtualenv
source virtualenv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python develop

Teuthology in PyPI

However if you prefer, you may install teuthology from PyPI:

pip install teuthology

Note: The version in PyPI can be (far) behind the development version.

Or from GitHub:

pip install git+[orchestra]

where the dependencies for orchestrating are installed. They are used for interacting with the services to schedule tests and to report the test results.

Update Dependencies

We track the dependencies using requirements.txt. These packages are tested, and should work with teuthology. But if you want to bump up the versions of them, please use the following command to update these files:

./ -P <package-name>

Please upgrade pip-tool using following command

pip install pip-tools --upgrade

if the command above fails like:

Traceback (most recent call last):
File "/home/kchai/teuthology/virtualenv/bin/pip-compile", line 5, in <module>
  from piptools.scripts.compile import cli
File "/home/kchai/teuthology/virtualenv/local/lib/python2.7/site-packages/piptools/scripts/", line 11, in <module>
  from pip.req import InstallRequirement, parse_requirements
ImportError: No module named req

Add Dependencies

td,dr: please add the new dependencies in both and

We also use pip install <URL> to install teuthology in some Ceph’s unit tests. To cater their needs, some requirements are listed in as well, so that pip install can pick them up. We could just avoid duplicating the packages specifications in two places by putting:

-e .[orchestra,test]

in But dependabot includes:

-e file:///home/dependabot/dependabot-updater/tmp/dependabot_20200617-72-1n8af4b  # via -r

in the generated requirements.txt. This renders the created pull request useless without human intervention. To appease dependabot, a full-blown collecting all direct dependencies listed by is used instead.