# How the vt_list_guests Plugin Discovers and Displays Available Guest Operating Systems

> Learn how the vt_list_guests plugin discovers and displays guest OS by parsing config files, applying filters, and checking disk images. Get the details.

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

---

**The vt_list_guests plugin discovers available guest operating systems by parsing the machines.cfg and guest-os.cfg configuration files for the selected backend, applying optional filters for architecture and OS type, and verifying whether the corresponding disk images exist on disk before displaying the results.**

The vt_list_guests command is a core utility in the avocado-vt testing framework that enumerates usable guest OS images for virtualization testing. According to the avocado-framework/avocado-vt source code, the plugin operates through a three-stage pipeline that bridges configuration parsing with filesystem validation to present an accurate list of available guests.

## CLI Command Registration and Option Parsing

The plugin entry point resides in [`avocado_vt/plugins/vt_list_guests.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_list_guests.py), where the `VTListGuests` class registers command-line options during the configuration phase.

```python

# avocado_vt/plugins/vt_list_guests.py

settings.register_option(section, key="guest_os", default=None,
                        help_msg="List only specific guests")
add_option(parser, dest="vt.list_guests.guest_os", arg="--guest-os")
add_option(parser, dest="vt.type", arg="--vt-type")

```

The `--guest-os` flag allows users to filter for specific operating systems, while `--vt-type` specifies the backend (e.g., `qemu` or `libvirt`). During execution, the `run` method invokes the discovery chain:

```python
guest_name_parser = get_guest_name_parser(
    config, guest_os="vt.list_guests.guest_os")
guest_listing(config, guest_name_parser)

```

## Guest Name Parsing and Configuration Loading

The `get_guest_name_parser()` function in [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py) builds a Cartesian configuration parser that reads backend-specific definitions.

```python
machines_cfg_path = data_dir.get_backend_cfg_path(
    get_opt(options, "vt.type"), "machines.cfg")
guest_os_cfg_path = data_dir.get_backend_cfg_path(
    get_opt(options, "vt.type"), "guest-os.cfg")
cartesian_parser.parse_file(machines_cfg_path)
cartesian_parser.parse_file(guest_os_cfg_path)

```

### Backend Configuration Files

The parser loads two critical files:

- **machines.cfg**: Defines machine types and hardware profiles supported by the backend
- **guest-os.cfg**: Contains operating system definitions and their associated parameters

### Filter Application

After parsing, the system applies filters based on user-provided constraints:

- `vt.common.arch` – Target architecture (e.g., x86_64, aarch64)
- `vt.common.machine_type` – Specific machine variant
- `vt.list_guests.guest_os` – Operating system name filter

## Image Verification and Output Generation

The `guest_listing()` function in [`avocado_vt/loader.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/loader.py) iterates over the parsed guest definitions and performs filesystem validation.

```python
for params in guest_name_parser.get_dicts():
    base_dir = params.get("images_base_dir", data_dir.get_data_dir())
    image_name = storage.get_image_filename(params, base_dir)
    machine_type = get_opt(config, "vt.common.machine_type")
    name = params["name"].replace(".%s" % machine_type, "")
    if os.path.isfile(image_name):
        out = name
    else:
        missing = "(missing %s)" % os.path.basename(image_name)
        out = name + " " + output.TERM_SUPPORT.warn_header_str(missing)
    LOG.debug(out)

```

For each guest definition yielded by the parser:

1. **Image Path Resolution**: `storage.get_image_filename()` constructs the absolute path to the disk image using the `images_base_dir` parameter or the default data directory.
2. **Existence Check**: The code verifies whether the image file exists using `os.path.isfile()`.
3. **Name Normalization**: The machine type suffix is stripped from the guest name for cleaner display.
4. **Output Generation**: Available guests display their name only; missing images append a colored warning indicating the missing filename.

## Practical Usage Examples

List all guests for the default QEMU backend:

```bash
avocado vt-list-guests

```

Filter for a specific operating system:

```bash
avocado vt-list-guests --guest-os fedora30

```

Specify an alternative backend:

```bash
avocado vt-list-guests --vt-type libvirt

```

Sample output indicating both available and missing images:

```

fedora30
centos7 (missing centos7-64.qcow2)
ubuntu20.04

```

## Summary

- The plugin registers `--guest-os` and `--vt-type` CLI options in [`avocado_vt/plugins/vt_list_guests.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_list_guests.py) to control filtering and backend selection.
- Guest definitions are loaded from [`machines.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/machines.cfg) and [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg) via `get_guest_name_parser()` in [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py).
- The Cartesian parser applies filters for architecture (`vt.common.arch`), machine type (`vt.common.machine_type`), and specific guest OS names.
- `guest_listing()` in [`avocado_vt/loader.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/loader.py) validates image existence using `storage.get_image_filename()` and `os.path.isfile()`.
- The output displays normalized guest names, appending warnings for any missing disk image files.

## Frequently Asked Questions

### What configuration files does vt_list_guests use to discover guest operating systems?

The plugin reads [`machines.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/machines.cfg) and [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg) from the backend-specific configuration directory. These files are located using `data_dir.get_backend_cfg_path()` based on the current `vt.type` setting (e.g., qemu or libvirt). The Cartesian parser processes these files to enumerate all valid guest and machine combinations.

### How does the plugin determine if a guest image is available?

For each parsed guest definition, the plugin calls `storage.get_image_filename()` to resolve the absolute path to the disk image. It then checks `os.path.isfile(image_name)` to verify physical existence on the filesystem. If the file is missing, the output appends a warning message containing the expected filename.

### Can I filter the guest list by architecture or machine type?

Yes. The `get_guest_name_parser()` function applies filters for `vt.common.arch` and `vt.common.machine_type` during the parsing phase. Additionally, you can use the `--guest-os` CLI option to restrict results to specific operating system names, such as `fedora30` or `centos7`.

### Where is the core guest listing logic implemented?

The primary implementation resides in [`avocado_vt/loader.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/loader.py) within the `guest_listing()` function. This function receives a configured Cartesian parser from [`virttest/standalone_test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/standalone_test.py) and handles the iteration, image verification, and formatted output generation that appears in the terminal.