# How the vt_bootstrap Plugin Downloads Guest Images and Test Providers in Avocado-VT

> Learn how the vt_bootstrap plugin in Avocado-VT efficiently downloads guest images and test providers, cloning repos and managing OS images via virttest/bootstrap.py.

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

---

**The `vt_bootstrap` plugin orchestrates environment setup by cloning test provider git repositories and downloading, verifying, and decompressing guest OS images through the core [`virttest/bootstrap.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/bootstrap.py) module.**

The `vt_bootstrap` command is the standard entry point for initializing Avocado-VT test environments. When you run this command, the plugin delegates all heavy lifting to the underlying bootstrap framework, which handles both version-controlled test assets and binary guest images required for virtualization testing.

## Entry Point: The VTBootstrap Plugin

The CLI command is implemented in [`avocado_vt/plugins/vt_bootstrap.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_bootstrap.py) by the `VTBootstrap` class. When a user executes:

```bash
avocado vt-bootstrap [options]

```

The `run()` method collects parsed arguments and forwards them directly to the core bootstrap routine:

```python
bootstrap.bootstrap(options=config, interactive=True)  # virttest/bootstrap.py

```

This single call triggers the complete setup workflow, separating the Avocado plugin interface from the domain-specific logic that manages test providers and guest images.

## How Test Providers Are Downloaded and Configured

Test providers are git repositories containing test cases and configuration data. The bootstrap process ensures these are synchronized locally through three distinct phases.

### Synchronizing the Provider Directory Structure

First, the bootstrap script establishes a writable local copy of the reference test providers. It copies the base provider directory to the user’s local data directory:

```python
shutil.copytree(tp_base_dir, tp_local_dir, dirs_exist_ok=True)

```

The paths are resolved through `data_dir.get_base_test_providers_dir()` and `data_dir.get_test_providers_dir()` in [`virttest/data_dir.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/data_dir.py), ensuring platform-agnostic path management.

### Detecting Missing Providers

The system scans for providers that have never been cloned by checking for the absence of `.git` subdirectories. The function `asset.test_providers_not_downloaded()` in [`virttest/asset.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/asset.py) iterates through all entries in `test-providers.d/`:

```python
not_downloaded = asset.test_providers_not_downloaded()

```

This returns a list of provider names requiring initial cloning.

### Cloning and Updating Provider Repositories

If the user has not disabled downloads via `--vt-no-downloads`, the bootstrap calls `asset.download_all_test_providers(update_flag)`. This function, located in [`virttest/asset.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/asset.py), iterates through all provider names and invokes:

```python
def download_all_test_providers(update=False):
    for provider in get_test_provider_names():
        download_test_provider(provider, update)

```

For each provider, the system:

1. **Resolves the git URL** from the provider’s [`provider.ini`](https://github.com/avocado-framework/avocado-vt/blob/main/provider.ini) configuration file
2. **Clones or updates** the repository using `git.get_repo()` (or `git pull` when updating)
3. **Verifies integrity** by running `git log -1` to confirm the repository is functional

## How Guest Images Are Downloaded and Prepared

Guest images are binary assets defined in Cartesian configuration files. The bootstrap process parses these definitions, downloads the corresponding files, and prepares them for use.

### Parsing Guest OS Requirements

For the selected virtualization type (`--vt-type`), the bootstrap code identifies required assets by parsing Cartesian configuration files. It calls:

```python
get_guest_os_info_list(vt_type, guest_os)

```

This function reads [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg) (located via `data_dir.get_backend_cfg_path()`) to extract asset names such as `JeOS.27.x86_64`. The default guest OS and architecture are sourced from [`virttest/defaults.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/defaults.py) (`DEFAULT_GUEST_OS` and `ARCH` constants).

### Downloading and Verifying Assets

For each asset name, the system invokes:

```python
asset.download_asset(os_asset, interactive=interactive, restore_image=True)

```

The `download_asset()` function in [`virttest/asset.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/asset.py) performs the following:

1. **Loads asset metadata** via `get_asset_info()`, parsing the corresponding `.ini` file
2. **Checks SHA-1 integrity** by comparing the local file hash against the `sha1_url` entry
3. **Downloads when necessary** using `download.url_download_interactive()` if the file is missing, corrupted, or mismatched
4. **Handles decompression** by calling `uncompress_asset()` for compressed archives (`.xz`, `.gz`)

The `download_file()` function encapsulates this logic:

```python
def download_file(asset_info, interactive=False, force=False):
    # Verify SHA1, download if needed, then...

    uncompress_asset(asset_info, force=force)

```

### Image Restoration

When `restore_image=True` is passed (the default in the bootstrap context), the system ensures the uncompressed image exists even if the compressed archive is already present. This guarantees the guest image is immediately ready for test execution without manual extraction.

## Common Bootstrap Workflows

Run a basic bootstrap for the default QEMU backend:

```bash
avocado vt-bootstrap

```

Force a complete refresh of providers and re-download all assets:

```bash
avocado vt-bootstrap \
    --vt-update-providers \
    --vt-update-config \
    --yes-to-all

```

Programmatically trigger bootstrap from a custom script:

```python
from virttest import bootstrap, defaults

options = {
    "vt.type": "qemu",
    "vt.guest_os": f"{defaults.DEFAULT_GUEST_OS}.{defaults.ARCH}",
}
bootstrap.bootstrap(options, interactive=False)

```

## Summary

- **Entry point**: The `VTBootstrap` class in [`avocado_vt/plugins/vt_bootstrap.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_bootstrap.py) forwards CLI arguments to [`virttest/bootstrap.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/bootstrap.py).
- **Provider setup**: The system clones git repositories listed in `test-providers.d/` using functions in [`virttest/asset.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/asset.py), synchronizing local copies with remote sources.
- **Guest image handling**: Cartesian configuration files define required assets; `download_asset()` verifies SHA-1 hashes, downloads missing files, and decompresses images automatically.
- **Path management**: [`virttest/data_dir.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/data_dir.py) centralizes all filesystem paths for downloads, providers, and configuration files.
- **Defaults**: [`virttest/defaults.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/defaults.py) supplies standard guest OS identifiers and architecture strings used during bootstrap.

## Frequently Asked Questions

### Where does vt_bootstrap store downloaded guest images?

According to the avocado-vt source code, guest images are stored in the directory returned by `data_dir.get_download_dir()`, typically located under `~/avocado/data/avocado-vt/downloads/` or the system-wide Avocado data directory. The specific path varies by platform and Avocado configuration, but all locations are centralized through [`virttest/data_dir.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/data_dir.py).

### Can I run vt_bootstrap without downloading anything?

Yes. Pass the `--vt-no-downloads` flag to skip all network operations. In this mode, the bootstrap script still synchronizes the test provider directory structure and verifies local asset integrity, but it will not clone new git repositories or download missing guest images. This is useful for offline environments where assets are pre-staged manually.

### How does vt_bootstrap verify the integrity of downloaded files?

The bootstrap process uses SHA-1 verification implemented in [`virttest/asset.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/asset.py). For each asset, the `download_file()` function retrieves the expected hash from the `sha1_url` field in the asset’s `.ini` configuration file. It computes the local file’s SHA-1 hash and compares it; if the hashes mismatch or the file is missing, it triggers a fresh download via `download.url_download_interactive()`.

### What virtualization backends does vt_bootstrap support?

The `vt_bootstrap` command supports any backend defined in the Avocado-VT Cartesian configuration files, including `qemu`, `libvirt`, and `lvsb`. You specify the target backend using the `--vt-type` option (e.g., `--vt-type qemu`). The bootstrap code then loads the corresponding [`guest-os.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/guest-os.cfg) from the backend-specific directory to determine which guest images to download.