virt-v2v-output-local - Man Page

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:

-o libvirt -os POOL
-os POOL

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.

-o local -os DIRECTORY

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.

-o qemu -os DIRECTORY
-o qemu -os DIRECTORY --qemu-boot

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.

-o json -os DIRECTORY

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.

-o null

The guest is converted, but the final result is thrown away and no metadata is created.  This is mainly useful for testing.

Output to Libvirt

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

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

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

     virsh define /var/tmp/NAME.xml

Output to JSON

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.

See Also



Richard W.M. Jones


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.


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:

Referenced By


2022-01-17 virt-v2v-1.45.97 Virtualization Support