virt-v2v-output-local(1)

📦
version 2.13.8 · 14 versions
, in centos-stream 10

💅 virt-v2v-output-local — bestie's guide to local output 💅

Okay so this is a page from the Virtualization Support corner of the man-verse (it's virt-v2v-output-local(1) if we're being formal ✨), and it's literally all about how to make virt-v2v(1) drop your converted guests into local files or into a libvirt instance running on your own machine. Obsessed already? Same. 🫶

🌸 NAME 🌸

virt-v2v-output-local — using virt-v2v to convert guests to local files or libvirt. That's the whole gig, no cap. 💖

✨ SYNOPSIS ✨

 virt-v2v [-i* options] [-o libvirt] -os POOL

 virt-v2v [-i* options] -o local -os DIRECTORY

 virt-v2v [-i* options] -o qemu -os DIRECTORY

 virt-v2v [-i* options] -o null

Look at those four little moods. Pick your fave, bestie. 🎀

🦋 DESCRIPTION 🦋

So this page is the tutorial for using virt-v2v(1) to convert guests over to local files, or to a libvirt instance that's running locally. And ngl, there are four output modes you get to pick from on the virt-v2v command line, and they are, in order:

  • -o libvirt -os POOL
  • -os POOL — This one converts the guest into a libvirt directory pool called POOL, and instantiates the guest inside libvirt (but heads up: it does not start it running, so don't come for it if it's not booting 🙈). Peep "OUTPUT TO LIBVIRT" below for the deets.

Also! -o libvirt is the default when you don't pass any -o option at all, so you can literally just omit it like it's not even a thing. Lowkey convenient. 💅

  • -o local -os DIRECTORY — This one converts the guest into files inside DIRECTORY. You also get a libvirt XML file created — but unlike -o libvirt, the guest is not instantiated in libvirt. Only files get made. That's it. Very demure.

The files come out named like this:

 NAME-sda, NAME-sdb, etc.      Guest disk(s).
 NAME.xml                      Libvirt XML.

where NAME is the guest name. Cute, consistent, iconic. ⭐

  • -o qemu -os DIRECTORY — This one also converts the guest into files inside DIRECTORY. The twist: unlike -o local up there, you get a shell script that contains the raw qemu command you'd need to actually boot the guest. But bestie, listen — the shell script is not run. It's there for you to run later, on your own terms. Main character energy. 👑
  • -o null — The guest gets converted, but then the final result is straight-up thrown away and no metadata is created at all. This is mainly useful for testing. It's giving "the journey was the friends we made along the way." 💀

🌈 OUTPUT TO LIBVIRT 🌈

The -o libvirt option is how you upload the converted guest onto a libvirt-managed host. And okay, before you get too excited, there are several limitations and I need you to know them:

  • You can only use a local libvirt connection [see below for how to workaround this].
  • The -os pool option must specify a directory pool, not anything more exotic such as iSCSI [but see below].
  • You can only upload to a KVM hypervisor.

Yeah. But don't spiral — there's a workaround, and it slays. 🧚

🎀 Workaround for output to a remote libvirt instance and/or a non-directory storage pool 🎀

  1. Use virt-v2v in -o local mode to convert the guest disks and metadata into a local temporary directory:
 virt-v2v [...] -o local -os /var/tmp

This creates two (or more) files in /var/tmp called:

 /var/tmp/NAME.xml     # the libvirt XML (metadata)
 /var/tmp/NAME-sda     # the guest’s first disk

(for NAME substitute the guest's name, iykyk 💖).

  1. Upload the converted disk(s) into the storage pool called POOL:
 size=$(stat -c%s /var/tmp/NAME-sda)
 virsh vol-create-as POOL NAME-sda $size --format raw
 virsh vol-upload --pool POOL NAME-sda /var/tmp/NAME-sda
  1. Edit /var/tmp/NAME.xml to change /var/tmp/NAME-sda to the pool name. In other words, locate the following bit of XML:
 <disk type='file' device='disk'>
   <driver name='qemu' type='raw' />
   <source file='/var/tmp/NAME-sda' />
   <target dev='hda' bus='ide' />
 </disk>

and change two things: the type='file' attribute must be changed to type='volume', and the <source> element must be changed to include pool and volume attributes:

 <disk type='volume' device='disk'>
   ...
   <source pool='POOL' volume='NAME-sda' />
   ...
 </disk>

Two edits. That's it. You got this. 💪

  1. Define the final guest in libvirt:
 virsh define /var/tmp/NAME.xml

And boom — remote libvirt, non-directory pool, all handled. Periodt. 🔥

🍓 SEE ALSO 🍓

That's the whole list, go read it, it's the parent page and it's kind of a big deal. 🌟

💜 AUTHOR 💜

Richard W.M. Jones — the legend behind all this. 🫶

Copyright (C) 2009-2025 Red Hat Inc. — protect it at all costs.

📜 LICENSE 📜

Okay so legally speaking (and I'm quoting the vibe, not skipping anything):

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.

💀 Yeah the all-caps warranty bit is real and it's not me being dramatic for once. No warranty, bestie. None.

🐛 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 — and I'm begging you, don't skip these, the maintainers will cry 😭:

  • 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.
🙈 "Complete, unedited" means don't trim it, don't summarize it, don't vibe-edit it. Paste the whole thing. The whole thing. 💅

Okay that's the page!! This was virt-v2v-output-local from virt-v2v-2.13.8, dated 2026-10-05 — mwah, go convert something, bestie 💖✨🎀🦋

📦 where this page comes from