3 usage: qemu-img command [command options]
7 @c man begin DESCRIPTION
8 qemu-img allows you to create, convert and modify images offline. It can handle
9 all image formats supported by QEMU.
11 @b{Warning:} Never use qemu-img to modify images in use by a running virtual
12 machine or any other process; this may destroy the image. Also, be aware that
13 querying an image that is being modified by another process may encounter
19 The following commands are supported:
21 @include qemu-img-cmds.texi
26 is a disk image filename
28 is the disk image format. It is guessed automatically in most cases. See below
29 for a description of the supported disk formats.
32 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
33 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
34 and T (terabyte, 1024G) are supported. @code{b} is ignored.
37 is the destination disk image filename
40 is the destination format
42 is a comma separated list of format specific options in a
43 name=value format. Use @code{-o ?} for an overview of the options supported
44 by the used format or see the format descriptions below for details.
48 indicates that target image must be compressed (qcow format only)
50 with or without a command shows help and lists the supported formats
52 display progress bar (convert and rebase commands only)
54 indicates the consecutive number of bytes that must contain only zeros
55 for qemu-img to create a sparse image during conversion. This value is rounded
56 down to the nearest 512 bytes. You may use the common size suffixes like
57 @code{k} for kilobytes.
59 specifies the cache mode that should be used with the (destination) file. See
60 the documentation of the emulator's @code{-drive cache=...} option for allowed
64 Parameters to snapshot subcommand:
69 is the name of the snapshot to create, apply or delete
71 applies a snapshot (revert disk to saved state)
77 lists all snapshots in the given image
83 @item check [-f @var{fmt}] @var{filename}
85 Perform a consistency check on the disk image @var{filename}.
87 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
90 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
92 Create the new disk image @var{filename} of size @var{size} and format
93 @var{fmt}. Depending on the file format, you can add one or more @var{options}
94 that enable additional features of this format.
96 If the option @var{backing_file} is specified, then the image will record
97 only the differences from @var{backing_file}. No size needs to be specified in
98 this case. @var{backing_file} will never be modified unless you use the
99 @code{commit} monitor command (or qemu-img commit).
101 The size can also be specified using the @var{size} option with @code{-o},
102 it doesn't need to be specified separately in this case.
104 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
106 Commit the changes recorded in @var{filename} in its base image.
108 @item convert [-c] [-p] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
110 Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
111 using format @var{output_fmt}. It can be optionally compressed (@code{-c}
112 option) or use any format specific options like encryption (@code{-o} option).
114 Only the formats @code{qcow} and @code{qcow2} support compression. The
115 compression is read-only. It means that if a compressed sector is
116 rewritten, then it is rewritten as uncompressed data.
118 Image conversion is also useful to get smaller image when using a
119 growable format such as @code{qcow} or @code{cow}: the empty sectors
120 are detected and suppressed from the destination image.
122 You can use the @var{backing_file} option to force the output image to be
123 created as a copy on write image of the specified base image; the
124 @var{backing_file} should have the same content as the input's base image,
125 however the path, image format, etc may differ.
127 @item info [-f @var{fmt}] @var{filename}
129 Give information about the disk image @var{filename}. Use it in
130 particular to know the size reserved on disk which can be different
131 from the displayed size. If VM snapshots are stored in the disk image,
132 they are displayed too.
134 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
136 List, apply, create or delete snapshots in image @var{filename}.
138 @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
140 Changes the backing file of an image. Only the formats @code{qcow2} and
141 @code{qed} support changing the backing file.
143 The backing file is changed to @var{backing_file} and (if the image format of
144 @var{filename} supports this) the backing file format is changed to
147 There are two different modes in which @code{rebase} can operate:
150 This is the default mode and performs a real rebase operation. The new backing
151 file may differ from the old one and qemu-img rebase will take care of keeping
152 the guest-visible content of @var{filename} unchanged.
154 In order to achieve this, any clusters that differ between @var{backing_file}
155 and the old backing file of @var{filename} are merged into @var{filename}
156 before actually changing the backing file.
158 Note that the safe mode is an expensive operation, comparable to converting
159 an image. It only works if the old backing file still exists.
162 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
163 backing file name and format of @var{filename} is changed without any checks
164 on the file contents. The user must take care of specifying the correct new
165 backing file, or the guest-visible content of the image will be corrupted.
167 This mode is useful for renaming or moving the backing file to somewhere else.
168 It can be used without an accessible old backing file, i.e. you can use it to
169 fix an image whose backing file has already been moved/renamed.
172 You can use @code{rebase} to perform a ``diff'' operation on two
173 disk images. This can be useful when you have copied or cloned
174 a guest, and you want to get back to a thin image on top of a
175 template or base image.
177 Say that @code{base.img} has been cloned as @code{modified.img} by
178 copying it, and that the @code{modified.img} guest has run so there
179 are now some changes compared to @code{base.img}. To construct a thin
180 image called @code{diff.qcow2} that contains just the differences, do:
183 qemu-img create -f qcow2 -b modified.img diff.qcow2
184 qemu-img rebase -b base.img diff.qcow2
187 At this point, @code{modified.img} can be discarded, since
188 @code{base.img + diff.qcow2} contains the same information.
190 @item resize @var{filename} [+ | -]@var{size}
192 Change the disk image as if it had been created with @var{size}.
194 Before using this command to shrink a disk image, you MUST use file system and
195 partitioning tools inside the VM to reduce allocated file systems and partition
196 sizes accordingly. Failure to do so will result in data loss!
198 After using this command to grow a disk image, you must use file system and
199 partitioning tools inside the VM to actually begin using the new space on the
203 Supported image file formats:
208 Raw disk image format (default). This format has the advantage of
209 being simple and easily exportable to all other emulators. If your
210 file system supports @emph{holes} (for example in ext2 or ext3 on
211 Linux or NTFS on Windows), then only the written sectors will reserve
212 space. Use @code{qemu-img info} to know the real size used by the
213 image or @code{ls -ls} on Unix/Linux.
216 QEMU image format, the most versatile format. Use it to have smaller
217 images (useful if your filesystem does not supports holes, for example
218 on Windows), optional AES encryption, zlib based compression and
219 support of multiple VM snapshots.
224 File name of a base image (see @option{create} subcommand)
226 Image format of the base image
228 If this option is set to @code{on}, the image is encrypted.
230 Encryption uses the AES format which is very secure (128 bit keys). Use
231 a long password (16 characters) to get maximum protection.
234 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
235 sizes can improve the image file size whereas larger cluster sizes generally
236 provide better performance.
239 Preallocation mode (allowed values: off, metadata). An image with preallocated
240 metadata is initially larger but can improve performance when the image needs
246 Image format with support for backing files and compact image files (when your
247 filesystem or transport medium does not support holes). Good performance due
248 to less metadata than the more featureful qcow2 format, especially with
249 cache=writethrough or cache=directsync. Consider using qcow2 which will soon
250 have a similar optimization and is most actively developed.
255 File name of a base image (see @option{create} subcommand).
257 Image file format of backing file (optional). Useful if the format cannot be
258 autodetected because it has no header, like some vhd/vpc files.
260 Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
261 cluster sizes can improve the image file size whereas larger cluster sizes
262 generally provide better performance.
264 Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
265 and 16). There is normally no need to change this value but this option can be
266 used for performance benchmarking.
270 Old QEMU image format. Left for compatibility.
275 File name of a base image (see @option{create} subcommand)
277 If this option is set to @code{on}, the image is encrypted.
281 User Mode Linux Copy On Write image format. Used to be the only growable
282 image format in QEMU. It is supported only for compatibility with
283 previous versions. It does not work on win32.
285 VirtualBox 1.1 compatible image format.
287 VMware 3 and 4 compatible image format.
292 Image format of the base image
294 Create a VMDK version 6 image (instead of version 4)
298 VirtualPC compatible image format (VHD).
301 Linux Compressed Loop image, useful only to reuse directly compressed
302 CD-ROM images present for example in the Knoppix CD-ROMs.
310 @setfilename qemu-img
311 @settitle QEMU disk image utility
314 The HTML documentation of QEMU for more precise information and Linux
315 user mode emulator invocation.