Scroll to navigation

virt-v2v-output-local(1) Virtualization Support virt-v2v-output-local(1)


virt-v2v-output-local - Using virt-v2v to convert guests to local files or libvirt


 virt-v2v [-i* options] [-o libvirt] -os POOL
 virt-v2v [-i* options] -o local -os DIRECTORY
 virt-v2v [-i* options] -o qemu -os DIRECTORY [--qemu-boot]
 virt-v2v [-i* options] -o json -os DIRECTORY
                        [-oo json-disks-pattern=PATTERN]
 virt-v2v [-i* options] -o null


This page documents how to use virt-v2v(1) to convert guests to local files or to a locally running libvirt instance. There are four output modes you can select on the virt-v2v command line:

This converts the guest to a libvirt directory pool call "POOL", and instantiates the guest in libvirt (but does not start it running). See "OUTPUT TO LIBVIRT" below.

-o libvirt is the default if no -o option is given, so you can omit it.

This converts the guest to files in "DIRECTORY". A libvirt XML file is also created, but unlike -o libvirt the guest is not instantiated in libvirt, only files are created.

The files will be called:

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

where "NAME" is the guest name.

This converts the guest to files in "DIRECTORY". Unlike -o local above, a shell script is created which contains the raw qemu command you would need to boot the guest. However the shell script is not run, unless you also add the --qemu-boot option.
This converts the guest to files in "DIRECTORY". The metadata produced is a JSON file containing the majority of the data virt-v2v gathers during the conversion. See "OUTPUT TO JSON" below.
The guest is converted, but the final result is thrown away and no metadata is created. This is mainly useful for testing.


The -o libvirt option lets you upload the converted guest to a libvirt-managed host. There are several limitations:

  • 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.

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

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).

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
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' />

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' />
Define the final guest in libvirt:

 virsh define /var/tmp/NAME.xml


The -o json option produces the following files by default:

 NAME.json                     JSON metadata.
 NAME-sda, NAME-sdb, etc.      Guest disk(s).

where "NAME" is the guest name.

It is possible to change the pattern of the disks using the -oo json-disks-pattern=... option: it allows parameters in form of "%{...}" variables, for example:

 -oo json-disks-pattern=disk%{DiskNo}.img

Recognized variables are:

The index of the disk, starting from 1.
The destination device of the disk, e.g. "sda", "sdb", etc.
The name of the guest.

Using a pattern it is possible use subdirectories for the disks, even with names depending on variables; for example:

 -oo json-disks-pattern=%{GuestName}-%{DiskNo}/disk.img

The default pattern is "%{GuestName}-%{DiskDeviceName}".

If the literal "%{...}" text is needed, it is possible to avoid the escape it with a leading "%"; for example, "%%{GuestName}-%{DiskNo}.img" will create file names for the disks like "%%{GuestName}-1.img", "%%{GuestName}-2.img", etc.




Richard W.M. Jones


Copyright (C) 2009-2020 Red Hat Inc.



To get a list of bugs against libguestfs, use this link:

To report a new bug against libguestfs, use this link:

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.
2021-11-24 virt-v2v-1.44.2