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 will enumerate information about backing files in a disk image chain. Refer
33 below for further description.
36 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
37 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
38 and T (terabyte, 1024G) are supported. @code{b} is ignored.
41 is the destination disk image filename
44 is the destination format
46 is a comma separated list of format specific options in a
47 name=value format. Use @code{-o ?} for an overview of the options supported
48 by the used format or see the format descriptions below for details.
50 is param used for internal snapshot, format is
51 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
52 @item snapshot_id_or_name
53 is deprecated, use snapshot_param instead
56 indicates that target image must be compressed (qcow format only)
58 with or without a command shows help and lists the supported formats
60 display progress bar (compare, convert and rebase commands only).
61 If the @var{-p} option is not used for a command that supports it, the
62 progress is reported when the process receives a @code{SIGUSR1} signal.
64 Quiet mode - do not print any output (except errors). There's no progress bar
65 in case both @var{-q} and @var{-p} options are used.
67 indicates the consecutive number of bytes that must contain only zeros
68 for qemu-img to create a sparse image during conversion. This value is rounded
69 down to the nearest 512 bytes. You may use the common size suffixes like
70 @code{k} for kilobytes.
72 specifies the cache mode that should be used with the (destination) file. See
73 the documentation of the emulator's @code{-drive cache=...} option for allowed
75 @item -T @var{src_cache}
76 specifies the cache mode that should be used with the source file(s). See
77 the documentation of the emulator's @code{-drive cache=...} option for allowed
81 Parameters to snapshot subcommand:
86 is the name of the snapshot to create, apply or delete
88 applies a snapshot (revert disk to saved state)
94 lists all snapshots in the given image
97 Parameters to compare subcommand:
106 Strict mode - fail on on different image size or sector allocation
109 Parameters to convert subcommand:
114 Skip the creation of the target volume
120 @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] @var{filename}
122 Perform a consistency check on the disk image @var{filename}. The command can
123 output in the format @var{ofmt} which is either @code{human} or @code{json}.
125 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
126 during the check. @code{-r leaks} repairs only cluster leaks, whereas
127 @code{-r all} fixes all kinds of errors, with a higher risk of choosing the
128 wrong fix or hiding corruption that has already occurred.
130 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
133 In case the image does not have any inconsistencies, check exits with @code{0}.
134 Other exit codes indicate the kind of inconsistency found or if another error
135 occurred. The following table summarizes all exit codes of the check subcommand:
140 Check completed, the image is (now) consistent
142 Check not completed because of internal errors
144 Check completed, image is corrupted
146 Check completed, image has leaked clusters, but is not corrupted
148 Checks are not supported by the image format
152 If @code{-r} is specified, exit codes representing the image state refer to the
153 state after (the attempt at) repairing it. That is, a successful @code{-r all}
154 will yield the exit code 0, independently of the image state before.
156 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
158 Create the new disk image @var{filename} of size @var{size} and format
159 @var{fmt}. Depending on the file format, you can add one or more @var{options}
160 that enable additional features of this format.
162 If the option @var{backing_file} is specified, then the image will record
163 only the differences from @var{backing_file}. No size needs to be specified in
164 this case. @var{backing_file} will never be modified unless you use the
165 @code{commit} monitor command (or qemu-img commit).
167 The size can also be specified using the @var{size} option with @code{-o},
168 it doesn't need to be specified separately in this case.
170 @item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-d] [-p] @var{filename}
172 Commit the changes recorded in @var{filename} in its base image or backing file.
173 If the backing file is smaller than the snapshot, then the backing file will be
174 resized to be the same size as the snapshot. If the snapshot is smaller than
175 the backing file, the backing file will not be truncated. If you want the
176 backing file to match the size of the smaller snapshot, you can safely truncate
177 it yourself once the commit operation successfully completes.
179 The image @var{filename} is emptied after the operation has succeeded. If you do
180 not need @var{filename} afterwards and intend to drop it, you may skip emptying
181 @var{filename} by specifying the @code{-d} flag.
183 @item compare [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-s] [-q] @var{filename1} @var{filename2}
185 Check if two images have the same content. You can compare images with
186 different format or settings.
188 The format is probed unless you specify it by @var{-f} (used for
189 @var{filename1}) and/or @var{-F} (used for @var{filename2}) option.
191 By default, images with different size are considered identical if the larger
192 image contains only unallocated and/or zeroed sectors in the area after the end
193 of the other image. In addition, if any sector is not allocated in one image
194 and contains only zero bytes in the second one, it is evaluated as equal. You
195 can use Strict mode by specifying the @var{-s} option. When compare runs in
196 Strict mode, it fails in case image size differs or a sector is allocated in
197 one image and is not allocated in the second one.
199 By default, compare prints out a result message. This message displays
200 information that both images are same or the position of the first different
201 byte. In addition, result message can report different image size in case
204 Compare exits with @code{0} in case the images are equal and with @code{1}
205 in case the images differ. Other exit codes mean an error occurred during
206 execution and standard error output should contain an error message.
207 The following table sumarizes all exit codes of the compare subcommand:
216 Error on opening an image
218 Error on checking a sector allocation
220 Error on reading data
224 @item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
226 Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated)
227 to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c}
228 option) or use any format specific options like encryption (@code{-o} option).
230 Only the formats @code{qcow} and @code{qcow2} support compression. The
231 compression is read-only. It means that if a compressed sector is
232 rewritten, then it is rewritten as uncompressed data.
234 Image conversion is also useful to get smaller image when using a
235 growable format such as @code{qcow}: the empty sectors are detected and
236 suppressed from the destination image.
238 @var{sparse_size} indicates the consecutive number of bytes (defaults to 4k)
239 that must contain only zeros for qemu-img to create a sparse image during
240 conversion. If @var{sparse_size} is 0, the source will not be scanned for
241 unallocated or zero sectors, and the destination image will always be
244 You can use the @var{backing_file} option to force the output image to be
245 created as a copy on write image of the specified base image; the
246 @var{backing_file} should have the same content as the input's base image,
247 however the path, image format, etc may differ.
249 If the @code{-n} option is specified, the target volume creation will be
250 skipped. This is useful for formats such as @code{rbd} if the target
251 volume has already been created with site specific options that cannot
252 be supplied through qemu-img.
254 @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
256 Give information about the disk image @var{filename}. Use it in
257 particular to know the size reserved on disk which can be different
258 from the displayed size. If VM snapshots are stored in the disk image,
259 they are displayed too. The command can output in the format @var{ofmt}
260 which is either @code{human} or @code{json}.
262 If a disk image has a backing file chain, information about each disk image in
263 the chain can be recursively enumerated by using the option @code{--backing-chain}.
265 For instance, if you have an image chain like:
268 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
271 To enumerate information about each disk image in the above chain, starting from top to base, do:
274 qemu-img info --backing-chain snap2.qcow2
277 @item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
279 Dump the metadata of image @var{filename} and its backing file chain.
280 In particular, this commands dumps the allocation state of every sector
281 of @var{filename}, together with the topmost file that allocates it in
282 the backing file chain.
284 Two option formats are possible. The default format (@code{human})
285 only dumps known-nonzero areas of the file. Known-zero parts of the
286 file are omitted altogether, and likewise for parts that are not allocated
287 throughout the chain. @command{qemu-img} output will identify a file
288 from where the data can be read, and the offset in the file. Each line
289 will include four fields, the first three of which are hexadecimal
290 numbers. For example the first line of:
292 Offset Length Mapped to File
293 0 0x20000 0x50000 /tmp/overlay.qcow2
294 0x100000 0x10000 0x95380000 /tmp/backing.qcow2
297 means that 0x20000 (131072) bytes starting at offset 0 in the image are
298 available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting
299 at offset 0x50000 (327680). Data that is compressed, encrypted, or
300 otherwise not available in raw format will cause an error if @code{human}
301 format is in use. Note that file names can include newlines, thus it is
302 not safe to parse this output format in scripts.
304 The alternative format @code{json} will return an array of dictionaries
305 in JSON format. It will include similar information in
306 the @code{start}, @code{length}, @code{offset} fields;
307 it will also include other more specific information:
310 whether the sectors contain actual data or not (boolean field @code{data};
311 if false, the sectors are either unallocated or stored as optimized
315 whether the data is known to read as zero (boolean field @code{zero});
318 in order to make the output shorter, the target file is expressed as
319 a @code{depth}; for example, a depth of 2 refers to the backing file
320 of the backing file of @var{filename}.
323 In JSON format, the @code{offset} field is optional; it is absent in
324 cases where @code{human} format would omit the entry or exit with an error.
325 If @code{data} is false and the @code{offset} field is present, the
326 corresponding sectors in the file are not yet in use, but they are
329 For more information, consult @file{include/block/block.h} in QEMU's
332 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
334 List, apply, create or delete snapshots in image @var{filename}.
336 @item rebase [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
338 Changes the backing file of an image. Only the formats @code{qcow2} and
339 @code{qed} support changing the backing file.
341 The backing file is changed to @var{backing_file} and (if the image format of
342 @var{filename} supports this) the backing file format is changed to
343 @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty
344 string), then the image is rebased onto no backing file (i.e. it will exist
345 independently of any backing file).
347 @var{cache} specifies the cache mode to be used for @var{filename}, whereas
348 @var{src_cache} specifies the cache mode for reading backing files.
350 There are two different modes in which @code{rebase} can operate:
353 This is the default mode and performs a real rebase operation. The new backing
354 file may differ from the old one and qemu-img rebase will take care of keeping
355 the guest-visible content of @var{filename} unchanged.
357 In order to achieve this, any clusters that differ between @var{backing_file}
358 and the old backing file of @var{filename} are merged into @var{filename}
359 before actually changing the backing file.
361 Note that the safe mode is an expensive operation, comparable to converting
362 an image. It only works if the old backing file still exists.
365 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
366 backing file name and format of @var{filename} is changed without any checks
367 on the file contents. The user must take care of specifying the correct new
368 backing file, or the guest-visible content of the image will be corrupted.
370 This mode is useful for renaming or moving the backing file to somewhere else.
371 It can be used without an accessible old backing file, i.e. you can use it to
372 fix an image whose backing file has already been moved/renamed.
375 You can use @code{rebase} to perform a ``diff'' operation on two
376 disk images. This can be useful when you have copied or cloned
377 a guest, and you want to get back to a thin image on top of a
378 template or base image.
380 Say that @code{base.img} has been cloned as @code{modified.img} by
381 copying it, and that the @code{modified.img} guest has run so there
382 are now some changes compared to @code{base.img}. To construct a thin
383 image called @code{diff.qcow2} that contains just the differences, do:
386 qemu-img create -f qcow2 -b modified.img diff.qcow2
387 qemu-img rebase -b base.img diff.qcow2
390 At this point, @code{modified.img} can be discarded, since
391 @code{base.img + diff.qcow2} contains the same information.
393 @item resize @var{filename} [+ | -]@var{size}
395 Change the disk image as if it had been created with @var{size}.
397 Before using this command to shrink a disk image, you MUST use file system and
398 partitioning tools inside the VM to reduce allocated file systems and partition
399 sizes accordingly. Failure to do so will result in data loss!
401 After using this command to grow a disk image, you must use file system and
402 partitioning tools inside the VM to actually begin using the new space on the
405 @item amend [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
407 Amends the image format specific @var{options} for the image file
408 @var{filename}. Not all file formats support this operation.
414 Supported image file formats:
419 Raw disk image format (default). This format has the advantage of
420 being simple and easily exportable to all other emulators. If your
421 file system supports @emph{holes} (for example in ext2 or ext3 on
422 Linux or NTFS on Windows), then only the written sectors will reserve
423 space. Use @code{qemu-img info} to know the real size used by the
424 image or @code{ls -ls} on Unix/Linux.
429 Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
430 @code{falloc} mode preallocates space for image by calling posix_fallocate().
431 @code{full} mode preallocates space for image by writing zeros to underlying
436 QEMU image format, the most versatile format. Use it to have smaller
437 images (useful if your filesystem does not supports holes, for example
438 on Windows), optional AES encryption, zlib based compression and
439 support of multiple VM snapshots.
444 Determines the qcow2 version to use. @code{compat=0.10} uses the
445 traditional image format that can be read by any QEMU since 0.10.
446 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
447 newer understand (this is the default). Amongst others, this includes zero
448 clusters, which allow efficient copy-on-read for sparse images.
451 File name of a base image (see @option{create} subcommand)
453 Image format of the base image
455 If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
457 The use of encryption in qcow and qcow2 images is considered to be flawed by
458 modern cryptography standards, suffering from a number of design problems:
461 @item The AES-CBC cipher is used with predictable initialization vectors based
462 on the sector number. This makes it vulnerable to chosen plaintext attacks
463 which can reveal the existence of encrypted data.
464 @item The user passphrase is directly used as the encryption key. A poorly
465 chosen or short passphrase will compromise the security of the encryption.
466 @item In the event of the passphrase being compromised there is no way to
467 change the passphrase to protect data in any qcow images. The files must
468 be cloned, using a different encryption passphrase in the new file. The
469 original file must then be securely erased using a program like shred,
470 though even this is ineffective with many modern storage technologies.
473 Use of qcow / qcow2 encryption is thus strongly discouraged. Users are
474 recommended to use an alternative encryption technology such as the
475 Linux dm-crypt / LUKS system.
478 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
479 sizes can improve the image file size whereas larger cluster sizes generally
480 provide better performance.
483 Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
484 @code{full}). An image with preallocated metadata is initially larger but can
485 improve performance when the image needs to grow. @code{falloc} and @code{full}
486 preallocations are like the same options of @code{raw} format, but sets up
490 If this option is set to @code{on}, reference count updates are postponed with
491 the goal of avoiding metadata I/O and improving performance. This is
492 particularly interesting with @option{cache=writethrough} which doesn't batch
493 metadata updates. The tradeoff is that after a host crash, the reference count
494 tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
495 check -r all} is required, which may take some time.
497 This option can only be enabled if @code{compat=1.1} is specified.
500 If this option is set to @code{on}, it will turn off COW of the file. It's only
501 valid on btrfs, no effect on other file systems.
503 Btrfs has low performance when hosting a VM image file, even more when the guest
504 on the VM also using btrfs as file system. Turning off COW is a way to mitigate
505 this bad performance. Generally there are two ways to turn off COW on btrfs:
506 a) Disable it by mounting with nodatacow, then all newly created files will be
507 NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
510 Note: this option is only valid to new or empty files. If there is an existing
511 file which is COW and has data blocks already, it couldn't be changed to NOCOW
512 by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
513 the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
518 QEMU also supports various other image file formats for compatibility with
519 older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), VHDX,
520 qcow1 and QED. For a full list of supported formats see @code{qemu-img --help}.
521 For a more detailed description of these formats, see the QEMU Emulation User
524 The main purpose of the block drivers for these formats is image conversion.
525 For running VMs, it is recommended to convert the disk images to either raw or
526 qcow2 in order to achieve good performance.
532 @setfilename qemu-img
533 @settitle QEMU disk image utility
536 The HTML documentation of QEMU for more precise information and Linux
537 user mode emulator invocation.