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
223   Sets the number of input blocks to copy
227   Sets the input file
231   Sets the output file
235   Sets the number of input blocks to skip
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.
863     options of ``raw`` format, but sets up metadata also.
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
932   of supported formats see ``qemu-img --help``.  For a more detailed