docs/tools/qemu-img.rst

6 --------
8 **qemu-img** [*standard options*] *command* [*command options*]
11 -----------
13 qemu-img allows you to create, convert and modify images offline. It can handle
16 **Warning:** Never use qemu-img to modify images in use by a running virtual
22 -------
24 .. program:: qemu-img
28 .. option:: -h, --help
32 .. option:: -V, --version
36 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
38   .. include:: ../qemu-option-trace.rst.inc
42 .. hxtool-doc:: qemu-img-cmds.hx
60 name=value format. Use ``-o help`` for an overview of the options supported
68   the -h option appearing both in the above option list and this one.
70 .. program:: qemu-img-common-opts
72 .. option:: --object OBJECTDEF
79 .. option:: --image-opts
83   exclusive with the *-f* parameter.
85 .. option:: --target-image-opts
89   exclusive with the *-O* parameters. It is currently required to also use
90   the *-n* parameter to skip image creation. This restriction may be relaxed
93 .. option:: --force-share (-U)
95   If specified, ``qemu-img`` will open the image in shared mode, allowing
100   images in read-only mode.
102 .. option:: --backing-chain
107 .. option:: -c
112   For qcow2, the compression algorithm can be specified with the ``-o
115 .. option:: -h
119 .. option:: -p
122   If the *-p* option is not used for a command that supports it, the
126 .. option:: -q
128   Quiet mode - do not print any output (except errors). There's no progress bar
129   in case both *-q* and *-p* options are used.
131 .. option:: -S SIZE
134   for ``qemu-img`` to create a sparse image during conversion. This value is
138 .. option:: -t CACHE
141   the documentation of the emulator's ``-drive cache=...`` option for allowed
144 .. option:: -T SRC_CACHE
147   the documentation of the emulator's ``-drive cache=...`` option for allowed
152 .. program:: qemu-img-compare
154 .. option:: -f
158 .. option:: -F
162 .. option:: -s
164   Strict mode - fail on different image size or sector allocation
168 .. program:: qemu-img-convert
170 .. option:: --bitmaps
174 .. option:: -n
178 .. option:: -m
182 .. option:: -W
184   Allow out-of-order writes to the destination. This option improves performance,
188 .. option:: -C
196 .. option:: -r
200 .. option:: --salvage
202   Try to ignore I/O errors when reading.  Unless in quiet mode (``-q``), errors
206 .. option:: --target-is-zero
210   that has a backing file. It is required to also use the ``-n``
215 .. program:: qemu-img-dd
239 .. program:: qemu-img-snapshot
245 .. option:: -a
249 .. option:: -c
253 .. option:: -d
257 .. option:: -l
263 .. program:: qemu-img-commands
265 .. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] [--force] -o OP…
272   instead be performed with ``qemu-img rebase``.
274   --force allows some unsafe operations. Currently for -f luks, it allows to
277 …-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFF…
279   Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
291   ``--no-drain`` is specified, a flush is issued without draining the request
294   if ``-i`` is specified, *AIO* option can be used to specify different
297   If ``-n`` is specified, the native AIO backend is used if possible. On
298   Linux, this option only works if ``-t none`` or ``-t directsync`` is
304 …--merge SOURCE | --add | --remove | --clear | --enable | --disable)... [-b SOURCE_FILE [-F SOURCE_…
309   ``--add`` to create *BITMAP*, enabled to record future edits.
311   ``--remove`` to remove *BITMAP*.
313   ``--clear`` to clear *BITMAP*.
315   ``--enable`` to change *BITMAP* to start recording future edits.
317   ``--disable`` to change *BITMAP* to stop recording future edits.
319   ``--merge`` to merge the contents of the *SOURCE* bitmap into *BITMAP*.
321   Additional options include ``-g`` which sets a non-default
322   *GRANULARITY* for ``--add``, and ``-b`` and ``-F`` which select an
324   ``--merge``.
326   To see what bitmaps are present in an image, use ``qemu-img info``.
328 .. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | al…
334   If ``-r`` is specified, qemu-img tries to repair any inconsistencies found
335   during the check. ``-r leaks`` repairs only cluster leaks, whereas
336   ``-r all`` fixes all kinds of errors, with a higher risk of choosing the
357   If ``-r`` is specified, exit codes representing the image state refer to the
358   state after (the attempt at) repairing it. That is, a successful ``-r all``
361 .. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-r RATE_…
372   *FILENAME* by specifying the ``-d`` flag.
380   garbage data when read. For this reason, ``-b`` implies ``-d`` (so that
383   The rate limit for the commit process is specified by ``-r``.
385 .. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] …
390   The format is probed unless you specify it by ``-f`` (used for
391   *FILENAME1*) and/or ``-F`` (used for *FILENAME2*) option.
397   can use Strict mode by specifying the ``-s`` option. When compare runs in
422 …--object OBJECTDEF] [--image-opts] [--target-image-opts] [--target-is-zero] [--bitmaps [--skip-bro…
426   be optionally compressed (``-c`` option) or use any format specific
427   options like encryption (``-o`` option).
430   compression is read-only. It means that if a compressed sector is
438   that must contain only zeros for ``qemu-img`` to create a sparse image during
451   If the ``-n`` option is specified, the target volume creation will be
454   be supplied through ``qemu-img``.
456   Out of order writes can be enabled with ``-W`` to improve performance.
464   Use of ``--bitmaps`` requests that any persistent bitmaps present in
467   ``--skip-broken-bitmaps`` is also specified to copy only the
470 .. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o O…
479   ``commit`` monitor command (or ``qemu-img commit``).
485   the ``-u`` option to enable unsafe backing file mode, which means that the
491   The size can also be specified using the *SIZE* option with ``-o``,
495 .. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BL…
506 .. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U…
514   the chain can be recursively enumerated by using the option ``--backing-chain``.
520     base.qcow2 <- snap1.qcow2 <- snap2.qcow2
526     qemu-img info --backing-chain snap2.qcow2
530   ``--backing-chain``, it is an array of ``ImageInfo`` objects.
532   ``--output=human`` reports the following information (for every image in the
557     auto-repaired the next time it is opened in qemu.
574 .. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=…
582   only dumps known-nonzero areas of the file.  Known-zero parts of the
584   throughout the chain.  ``qemu-img`` output will identify a file
607   - boolean field ``data``: true if the sectors contain actual data,
609     all-zero clusters
610   - boolean field ``zero``: true if the data is known to read as zero
611   - boolean field ``present``: true if the data belongs to the backing
614   - integer field ``depth``: the depth within the backing chain at
627 .. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] […
637   using ``qemu-img create``.  If *FILENAME* is given then act as if
638   converting an existing image file using ``qemu-img convert``.  The format
661   copy bitmaps from a source image in addition to the guest-visible
666 .. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT …
670 .. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE]…
691     new backing file may differ from the old one and ``qemu-img rebase``
692     will take care of keeping the guest-visible content of *FILENAME*
698     ``-c`` option specified, the clusters which are being merged (but not
706     ``qemu-img`` uses the unsafe mode if ``-u`` is specified. In this
709     specifying the correct new backing file, or the guest-visible
729     qemu-img create -f qcow2 -b modified.img diff.qcow2
730     qemu-img rebase -b base.img diff.qcow2
735 .. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--…
743   When shrinking images, the ``--shrink`` option must be given. This informs
744   ``qemu-img`` that the user acknowledges all loss of data beyond the truncated
751   When growing an image, the ``--preallocation`` option may be used to specify
759 -----
769   space. Use ``qemu-img info`` to know the real size used by the
770   image or ``ls -ls`` on Unix/Linux.
795     clusters, which allow efficient copy-on-read for sparse images.
807     used with the ``-c`` option of ``qemu-img convert``, but can also be used
816     128-bit AES-CBC.
822     - The AES-CBC cipher is used with predictable initialization
827     - The user passphrase is directly used as the encryption key. A
831     - In the event of the passphrase being compromised there is no way
838     - Initialization vectors used to encrypt sectors are based on the
851     Linux dm-crypt / LUKS system.
872     ``qemu-img check -r all`` is required, which may take some time.
885     - Disable it by mounting with nodatacow, then all newly created files
887     - For an empty file, add the NOCOW file attribute. That's what this
901     using this option with ``qemu-img create`` since ``qemu-img`` will create
903     update the reference to point to the given pre-existing file, use
904     ``qemu-img amend``.
908     file consistent as a standalone read-only raw image.
913     offset in the raw data file. This results in a read-only raw image. Writes
915     out-of-band writes may result in the metadata falling out of sync with the
931   including VMDK, VDI, VHD (vpc), VHDX, qcow1 and QED. For a full list
932   of supported formats see ``qemu-img --help``.  For a more detailed