# How to Configure Different Hypervisors Using the vt.type Option in Avocado-VT

> Learn how to configure hypervisors like Qemu and Libvirt in Avocado-VT using the vt.type option. Easily select backend hypervisors for seamless testing.

- Repository: [avocado/avocado-vt](https://github.com/avocado-framework/avocado-vt)
- Tags: how-to-guide
- Published: 2026-02-25

---

**The `vt.type` option selects your backend hypervisor by loading hypervisor-specific driver modules and configuration files from `virttest/backends/<type>/cfg/`.**

The `avocado-framework/avocado-vt` plugin provides a unified testing framework for multiple virtualization technologies. To switch between hypervisors like QEMU and Libvirt, you configure the `vt.type` option, which determines which backend driver is loaded and which default configuration files are parsed.

## Understanding the vt.type Option

The `vt.type` configuration key (exposed as `--vt-type` on the command line) acts as the single source of truth for hypervisor selection in Avocado-VT. When you set this option, the framework validates the value against supported backends, loads the corresponding driver module, and imports hypervisor-specific default configurations.

### Supported Hypervisor Backends

The framework supports multiple virtualization backends, each mapped to a specific driver module and configuration directory:

- **qemu**: Uses the QEMU driver and loads configurations from `virttest/backends/qemu/cfg/`
- **libvirt**: Uses the libvirt driver with configurations from `virttest/backends/libvirt/cfg/`
- **openvswitch**: Uses the openvswitch driver (inherits QEMU handling)
- **lvsb**: Uses the LVSB driver (no generic options)
- **spice**: Uses the Spice QA driver (independent of QEMU)

These values are defined in the `SUPPORTED_TEST_TYPES` list within [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py) (lines 27-36).

## How vt.type Works Under the Hood

The hypervisor selection process follows a four-stage pipeline implemented in [`avocado_vt/options.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/options.py) and related modules.

### Stage 1: Parsing and Validation

The option parser retrieves `vt.type` via `get_opt(self.config, "vt.type")` and validates it against `SUPPORTED_TEST_TYPES`. If the value is not recognized, the framework raises a configuration error before any backend code is loaded.

### Stage 2: Loading Backend Configuration Files

If no custom `--vt-config` is provided, the framework resolves default configuration paths using `data_dir.get_backend_cfg_path(vt_type, ...)` (implemented in [`virttest/data_dir.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/data_dir.py), lines 44-46). This function constructs paths to:

- [`machines.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/machines.cfg)
- [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg)
- [`tests.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/tests.cfg) (or [`tests-shared.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/tests-shared.cfg))

Located under `virttest/backends/<vt_type>/cfg/`.

### Stage 3: Applying Backend-Specific Options

After generic options are processed, `options._process_backend_specific_options(vt_type)` dispatches to specialized handlers:

- `_process_qemu_specific_options`
- `_process_libvirt_specific_options`

This occurs in [`avocado_vt/options.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/options.py) (lines 502-514), allowing each hypervisor to register unique command-line flags and configuration parameters.

### Stage 4: Building the Test Matrix

Finally, the Cartesian parser constructs the test matrix using the selected backend's configuration files and any additional filters you provide via command-line arguments.

## Practical Configuration Examples

### Command Line Usage

Select your hypervisor directly when running tests:

```bash

# Run tests using QEMU backend

avocado run my_test --vt-type qemu

# Run tests using libvirt backend (requires running libvirtd)

avocado run my_test --vt-type libvirt

```

The `--vt-type` flag is registered in [`avocado_vt/plugins/vt.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt.py) (lines 76-78) and processed by the `VirtTestOptionsProcess` class.

### Configuration File Method

Create a configuration file to set the default backend:

```ini
[vt]
type = libvirt

```

Run with the custom config:

```bash
avocado run my_test --vt-config myconfig.cfg

```

Alternatively, set the environment variable `AVOCADO_VT_TYPE` which the option parser reads from the configuration hierarchy.

### Python API Access

Inspect or set the backend programmatically:

```python
from avocado.utils import config
from avocado_vt.options import VirtTestOptionsProcess

# Simulate a config that contains vt.type

cfg = config.TestConfig()
cfg.set('vt.type', 'qemu')

# Process options (validates vt.type and loads backend)

options = VirtTestOptionsProcess(cfg)
parser = options.get_parser()

print(f"Backend selected: {cfg.get('vt.type')}")
print(f"Filters applied: {parser.only_filters}")

```

This triggers the same validation path used by the CLI (see `VirtTestOptionsProcess._process_options` in [`avocado_vt/options.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/options.py), lines 33-47).

## Backend-Specific Configuration Files

Each hypervisor backend maintains its own configuration directory under `virttest/backends/<type>/cfg/`. When you set `vt.type`, the framework automatically loads:

- **machines.cfg**: Defines machine types and hardware profiles
- **guest-os.cfg**: Specifies guest operating system variants
- **tests.cfg** or **tests-shared.cfg**: Defines test parameters and variants

For example, when using `--vt-type libvirt`, the framework loads [`virttest/backends/libvirt/cfg/machines.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/backends/libvirt/cfg/machines.cfg) instead of the QEMU equivalent, ensuring that libvirt-specific options like `connect_uri` or `driver_type` are available.

## Summary

- The `vt.type` option (CLI: `--vt-type`) is the single configuration key that determines which hypervisor backend Avocado-VT uses.
- Valid values are defined in `SUPPORTED_TEST_TYPES` within [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py) and include `qemu`, `libvirt`, `openvswitch`, `lvsb`, and `spice`.
- The framework loads backend-specific configuration files from `virttest/backends/<type>/cfg/` based on the selected type.
- Backend-specific option handlers in [`avocado_vt/options.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/options.py) apply hypervisor-unique parameters after generic processing.

## Frequently Asked Questions

### What happens if I specify an unsupported vt.type value?

The framework validates `vt.type` against the `SUPPORTED_TEST_TYPES` list in [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py) during the option processing stage. If you provide an unsupported value, Avocado-VT raises a configuration error immediately and exits before loading any backend code or configuration files.

### Can I use vt.type to switch between different libvirt connection URIs?

While `vt.type` selects the libvirt backend, connection URIs are controlled separately through the `vt.connect_uri` option or the `connect_uri` parameter in your configuration files. When `vt.type` is set to `libvirt`, the framework processes libvirt-specific options via `_process_libvirt_specific_options` in [`avocado_vt/options.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/options.py), where you can specify connection details.

### Do I need separate bootstrap commands for each hypervisor?

Yes. The `avocado vt-bootstrap` command respects the `--vt-type` flag to generate appropriate guest images and configuration files for the selected hypervisor. Run `avocado vt-bootstrap --vt-type qemu` for QEMU-specific assets or `avocado vt-bootstrap --vt-type libvirt` for libvirt-specific setups, as documented in `docs/source/GettingStartedGuide.rst` (lines 74-77).

### Where are the backend-specific test parameters defined?

Backend-specific parameters reside in the configuration files under `virttest/backends/<vt.type>/cfg/`. The `data_dir.get_backend_cfg_path()` function in [`virttest/data_dir.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/data_dir.py) (lines 44-46) constructs these paths dynamically based on the `vt.type` value, loading [`machines.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/machines.cfg), [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg), and [`tests.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/tests.cfg) specific to your selected hypervisor.