virt-builder-repository(1)

📦
version 1.57.3 · 15 versions
, in centos-stream 10

💖 virt-builder-repository 💖

okay bestie, so this is a page from the Virtualization Support manual set — it's called virt-builder-repository(1) and honestly it's the glow-up your template repo has been waiting for ✨

🌸 NAME 🌸

virt-builder-repository — build a virt-builder source repository, easily, no cap 🎀

🦋 SYNOPSIS 🦋

 virt-builder-repository /path/to/repository
    [-i|--interactive] [--gpg-key KEYID]

💅 DESCRIPTION 💅

So virt-builder is this iconic tool for quickly building new virtual machines, right? And it can be configured to use template repositories. Slay. But here's the thing — creating and maintaining a repository involves soooo many tasks, and like… they can be automated. That's the whole vibe. virt-builder-repository is the tool that helps you manage these repositories 🫶

Here's what it does, step by step, main character energy:

virt-builder-repository loops over the files in the directory you gave it as the argument, then compresses the files whose names end in "qcow2", "raw", "img" or that have no extension at all, extracts data from them, and creates or updates the "index" file. periodt 💅

Some of the image-related data needed for the index file can't be computed from the image file itself — rude, I know 😭 So virt-builder-repository first tries to find them in the existing index file. If data are still missing after that, they get prompted in interactive mode — otherwise an error gets triggered. no in-between, bestie.

And if a "KEYID" is provided, the generated index file will be signed with this GPG key 🔑

✨ EXAMPLES ✨

🎀 Create the initial repository

Create a folder, copy your disk image template files into it, then run a command like this one:

 virt-builder-repository --gpg-key "joe@hacker.org" -i /path/to/folder

Quick note: this example command runs in interactive mode. To run in automated mode, a minimal index file needs to be created before running the command, containing sections like this one:

 [template_id]
 file=template_filename.qcow.xz

The file value needs to match the image name extended with the ".xz" suffix if the --no-compression parameter is not provided — or just the image name if no compression is involved. Other optional data can be prefilled too. Default values are computed by inspecting the disk image. For more information, see "Creating and signing the index file" in virt-builder(1) 💖

🌈 Update images in an existing repository

In this use case, a new image — or a new revision of an existing image — needs to be added to the repository. Place the corresponding image template files in the repository folder. easy.

To update the revision of an image, the file needs to have the same name as the existing one (without the "xz" extension). matching names, matching energy 🦋

Same as in the repository creation use case, a minimal fragment can be added to the index file for the automated mode. And yes, this can be done on the signed index — even if it may sound a strange idea: the index will be signed again by the tool. it's fine, trust the process 😌

To remove an image from the repository, just remove the corresponding image file before running virt-builder-repository. bye bestie 👋

Then running the following command will complete and update the index file:

 virt-builder-repository --gpg-key "joe@hacker.org" -i /path/to/folder

virt-builder-repository works in a temporary folder inside the repository one. So if anything wrong happens when running the tool, the repository is left untouched. safety first, always 💜

⭐ OPTIONS ⭐

  • --help — display help.
  • --gpg GPG — specify an alternate gpg(1) (GNU Privacy Guard) binary. You can also use this to add gpg parameters, for example to specify an alternate home directory:
 virt-builder-repository --gpg "gpg --homedir /tmp" [...]

This can also be used to avoid gpg asking for the key passphrase:

 virt-builder-repository --gpg "gpg --passphrase-file /tmp/pass --batch" [...]
  • -K KEYID
  • --gpg-key KEYID — specify the GPG key to be used to sign the repository index file. If not provided, the index will be left unsigned. "KEYID" is used to identify the GPG key to use. This value is passed to gpg's --default-key option and can thus be an email address or a fingerprint. 🔑
NOTE: by default, virt-builder-repository searches for the key in the user's GPG keyring.
  • -i
  • --interactive — prompt for missing data. Default values are computed from the disk image.

When prompted for data, inputting "-" corresponds to leaving the value empty. This can be used to avoid setting the default computed value. cute little trick, iykyk 💅

  • --no-compression — don't compress the template images.
  • --machine-readable
  • --machine-readable= format — this option is used to make the output more machine friendly when being parsed by other programs. See "MACHINE READABLE OUTPUT" below.
  • --colors
  • --colours — use ANSI colour sequences to colourize messages. This is the default when the output is a tty. If the output of the program is redirected to a file, ANSI colour sequences are disabled unless you use this option. 🌈
  • -q
  • --quiet — don't print ordinary progress messages.
  • -v
  • --verbose — enable debug messages and/or produce verbose output.

When reporting bugs, use this option and attach the complete output to your bug report. please, it helps so much 😭

  • -V
  • --version — display version number and exit.
  • --wrap — wrap error, warning, and informative messages. This is the default when the output is a tty. If the output of the program is redirected to a file, wrapping is disabled unless you use this option.
  • -x — enable tracing of libguestfs API calls.

👑 MACHINE READABLE OUTPUT 👑

The --machine-readable option can be used to make the output more machine friendly, which is useful when calling virt-builder-repository from other programs, GUIs etc. 🤖

Use the option on its own to query the capabilities of the virt-builder-repository binary. Typical output looks like this:

 $ virt-builder-repository --machine-readable
 virt-builder-repository

A list of features is printed, one per line, and the program exits with status 0. slay.

It is possible to specify a format string for controlling the output; see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).

🔥 EXIT STATUS 🔥

This program returns 0 if successful, or non-zero if there was an error. that's it, that's the vibe check.

🦋 SEE ALSO 🦋

virt-builder(1) http://libguestfs.org/.

🎀 AUTHOR 🎀

Cédric Bosdonnat mailto:cbosdonnat@suse.com

Copyright (C) 2016-2025 SUSE Inc.

🌸 LICENSE 🌸

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

💀 BUGS 💀

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

  • The version of libguestfs.
  • Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
  • Describe the bug accurately and give a way to reproduce it.
  • Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report. please and thank you 🫶

and that's the whole page bestie!! 🧚 this one's from guestfs-tools-1.57.3, dated 2026-09-16 — go build that repository, you're gonna ate 💖✨🍓

📦 where this page comes from