# How the vt_init Plugin Initializes the VT Test Environment on First Use

> Learn how the vt_init plugin bootstraps the VT test environment. Discover configuration section registration, external file merging, and VirtTestLoader injection for first-time use.

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

---

**The vt_init plugin bootstraps the VT test environment by registering configuration sections, merging external config files, and injecting the VirtTestLoader into Avocado's plugin system during the first initialization cycle.**

When you run any Avocado command in the `avocado-framework/avocado-vt` repository, the `vt_init` plugin ensures the virtualization testing (VT) environment is fully configured. This happens transparently on first use through Avocado's plugin interface, setting up all necessary configuration hierarchies and test loaders required for virt-test execution.

## How the vt_init Plugin is Discovered

Avocado discovers the plugin through the entry point declared in [`setup.py`](https://github.com/avocado-framework/avocado-vt/blob/main/setup.py):

```python
avocado.plugins.init → vt-init = avocado_vt.plugins.vt_init:VtInit

```

This entry point maps to the `VtInit` class defined in [`avocado_vt/plugins/vt_init.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_init.py). When Avocado starts and loads plugins implementing the `Init` interface, it instantiates `VtInit` and calls its `initialize()` method.

## First-Time Initialization Guard

The plugin uses a guard mechanism to prevent duplicate configuration registration. Inside `initialize()`, the first check is:

```python
if not is_registering_settings_required():
    return

```

The `is_registering_settings_required()` function lives in [`virttest/compat.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/compat.py). It returns `True` only during the first plugin initialization cycle and `False` on subsequent runs, ensuring the VT environment setup happens exactly once.

## Configuration Section Registration

When the guard passes, `initialize()` creates the VT configuration hierarchy using `avocado.core.settings.settings.register_option`. The plugin registers the following sections:

- **vt** – High-level options including config file paths, guest OS selection, and filter lists (`settings.register_option(section, key="config", …)`)
- **vt.setup** – Image handling controls such as `backup_image_before_test` and restore operations
- **vt.common** – Global VM defaults including memory size (`mem`), architecture, and data directories
- **vt.qemu** – QEMU-specific settings including binary path (`qemu_bin`), acceleration type, device configurations, and sandboxing options
- **vt.libvirt** – Libvirt connection URI and related parameters
- **vt.debug** – Debug flags such as `no_cleanup` to preserve test artifacts
- **vt.filter** – Default filter overrides for test selection
- **plugins.vtjoblock** – Lock-file directory configuration for the vt-joblock plugin

After registering all options, the plugin merges external configuration files:

```python
settings.merge_with_configs()

```

This ensures user-provided settings in `/etc/avocado/conf.d/` or `~/.config/avocado/` override the defaults.

## Test Loader Registration

If the Avocado loader module is available (Avocado ≥ 82), the plugin registers the VT test loader:

```python
virt_loader = getattr(importlib.import_module("avocado_vt.loader"), "VirtTestLoader")
loader.register_plugin(virt_loader)

```

The `VirtTestLoader` class defined in [`avocado_vt/loader.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/loader.py) enables the `avocado vt` command to discover and execute virt-test tests using Cartesian configuration files.

## Summary

- The `vt_init` plugin is discovered via the `avocado.plugins.init` entry point in [`setup.py`](https://github.com/avocado-framework/avocado-vt/blob/main/setup.py).
- First-time initialization is guarded by `is_registering_settings_required()` in [`virttest/compat.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/compat.py) to prevent duplicate registrations.
- The plugin registers nine configuration sections (`vt`, `vt.setup`, `vt.common`, `vt.qemu`, `vt.libvirt`, `vt.debug`, `vt.filter`, `plugins.vtjoblock`) using `settings.register_option`.
- External configuration files are merged via `settings.merge_with_configs()`.
- The `VirtTestLoader` is registered with Avocado's loader system, enabling VT test discovery.

## Frequently Asked Questions

### What triggers the vt_init plugin to run?

The plugin runs whenever Avocado loads its plugin system, which happens on any Avocado command execution. The `initialize()` method is called automatically because `VtInit` implements the `Init` plugin interface registered under the `avocado.plugins.init` entry point.

### How does the plugin prevent settings from being registered multiple times?

The plugin calls `is_registering_settings_required()` from [`virttest/compat.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/compat.py) at the start of `initialize()`. This function returns `False` on subsequent runs after the first initialization, causing the method to return early and skip duplicate registrations.

### Where are the VT configuration options stored after registration?

The options are stored in Avocado's global settings object (`avocado.core.settings.settings`). They can be viewed using `avocado plugins --list vt` or overridden via command-line flags like `--vt-guest-os` or configuration files in `/etc/avocado/conf.d/`.