MKIMG(1)

📦
version 15.1 · 2 versions
, in freebsd 14.5, freebsd 15.1

💅 mkimg(1) — the girlies' guide to making disk images ✨

okay so first things first: this is the manual page for mkimg, and it lives in the General Commands Manual section of the FreeBSD man pages (that's the (1) bit, iykyk). Buckle up bestie, this one's a ride. 🎀

✨ NAME ✨

mkimg — the utility that makes disk images. that's it, that's the whole vibe. 💖

🦋 SYNOPSIS 🦋

mkimg [-H heads] [-P blksz] [-S secsz] [-T tracksz] [-b bootcode]
      [-c min_capacity] [-C max_capacity] [--capacity capacity]
      [-f format] [-h] [-o outfile] [-a active] [-t timestamp] [-v] [-y]
      [-s scheme [-p partition ...]]
mkimg --formats | --schemes | --version

🌸 DESCRIPTION 🌸

so mkimg builds a disk image out of the raw partition contents you feed it with the partition argument(s), using the partitioning scheme you name with the scheme argument. literally that's the whole job. 💅

where does the image go? stdout by default, bestie — or the file you name with the outfile argument. and the image file is a raw disk image unless you say otherwise, but you can pick the format with the format argument. ⭐ quick heads up: most formats need seekable output — the one exception is raw disk image. no cap.

🎀 making it bootable

you can make the disk image bootable by handing over the scheme-specific boot block contents with the bootcode argument and, depending on the scheme, with a boot partition. and here's the thing — the contents of that boot partition get provided exactly like any other partition, and mkimg does not treat it any differently from the other partitions. it's giving "no favourites here". 🫶

🧚 disk geometry (for the schemes that care)

some partitioning schemes need a disk geometry, and for those mkimg accepts the tracksz and heads arguments — those specify the number of sectors per track and the number of heads per cylinder respectively. old school but iconic. 📐

💜 logical vs physical sector size

both the logical and the physical sector size can be specified, and for that mkimg accepts the secsz and blksz arguments.

  • the secsz argument specifies the logical sector size. this is the sector size a disk reports when you query it for its capacity.
  • modern disks use a bigger sector size internally, referred to as block size by mkimg, and that's what the blksz argument sets.

and mkimg will use that (physical) block size to figure out the start of partitions and to round the size of the disk image. so yeah, it actually matters. 🔥

👑 capacity: -c, -C and --capacity

  • -c — sets a minimal capacity for the disk image. use it without the -s and -p options to create an empty disk image with the given (virtual) size. you can also write an empty partition table to the disk by specifying a partitioning scheme with the -s option but without specifying any partitions. and if the size required for all the partitions is larger than the given capacity, then the disk image will be larger than the capacity you gave. (she grows. respect it. 🌱)
  • -C — sets a maximum capacity for the disk image. if the combined sizes of the given partitions exceed the size given with -C, then image creation fails. full stop. 💀
  • --capacity — the shorthand that specifies the minimum and maximum capacity at the same time. efficiency queen. ✨

🕰️ timestamps and other flags

  • -t — causes any timestamps embedded in the output file to be set to the given time, specified in seconds since the epoch. ⏰
  • -h — prints a usage message and exits. the "help me bestie" button.
  • -v — increases the level of output that mkimg prints. the chattier the better, honestly. 🗣️
  • -y — ⚠️ testing purposes ONLY, not to be used in production. when present, mkimg will generate predictable values for Universally Unique Identifiers (UUIDs) and time stamps, so that consecutive runs of mkimg create images that are identical. great for tests, terrible for real life. don't do it, ok? 🙈

🌈 the active option (-a)

the active option marks a partition as active, if the partitioning scheme supports it. currently only the mbr scheme supports this concept.

by default, mkimg will only mark the first partition as active when boot code is specified. use the active option to override which partition is active. the number you specify corresponds to the number after the 's' in the partition's geom(8) name. and when the value is 0, no partitions are marked active. periodt. 🚫

🔍 the long options (the "tell me about yourself" set)

there's a whole set of long options that exist purely to query about mkimg itself. these should be given by themselves, because mkimg exits immediately after providing the requested info. main character energy: she answers, then she leaves. 💅

  • --version — prints the version of mkimg.
  • --formats — prints the list of supported output formats.
  • --schemes — prints the list of supported partitioning schemes.
  • both the format and scheme lists are space-separated lists, so they're easy to handle in scripts. 🧚

and if you want a more descriptive list of supported partitioning schemes or supported output formats — or a detailed description of how to specify partitions — just run mkimg with no arguments at all. it'll print a usage message with all the necessary details. the girl will explain everything. 🫶

🍓 DISK FORMATS 🍓

mkimg supports a number of output file formats. short descriptions below, go off. ✨

💙 QCOW and QCOW2

QCOW stands for "QEMU Copy On Write". it's a sparse file format akin to VHD and VMDK, and QCOW represents the first version. QCOW2 represents version 2 of the file format. version 2 is not backward compatible with version 1, and it adds support for snapshots among other things. the QCOW file formats are natively supported by QEMU and Xen. 🦋

  • to write QCOW, specify -f qcow on the command line.
  • to write version 2 QCOW, specify -f qcow2 on the command line.

the preferred file extension is .qcow and .qcow2 for QCOW and QCOW2 respectively, but .qcow is sometimes used for version 2 files as well. chaos, but that's the convention. 😭

💚 RAW file format

this file format is a sector by sector representation of an actual disk. there is no extra information that describes or relates to the format itself. the size of the file is the size of the (virtual) disk. this format is suitable for being copied onto a disk with utilities like dd. 💾

  • to write a raw disk file, either omit the -f option, or specify -f raw on the command line.

the preferred file extension is one of .img or .raw, but there's no real convention for it. do whatever feels right. 🌸

💜 Dynamic VHD and Fixed VHD

Microsoft's "Virtual Hard Disk" file formats. the dynamic format is a sparse format akin to QCOW and VMDK. the fixed format is effectively a raw format with a footer appended to the file, and as such it's often indistinguishable from the raw format. 👀

the fixed file format was added to support Microsoft's Azure platform, and due to inconsistencies in interpretation of the footer, it is not compatible with utilities like qemu when it is specifically instructed to interpret the file as a VHD file. by default qemu will treat the file as a raw disk file, which mostly works fine. 🫠

  • to have mkimg create a dynamic VHD file, specify -f vhd on the command line.
  • to create a fixed VHD file for use by Azure, specify -f vhdf on the command line.

the preferred file extension is .vhd. 🎀

⭐ Dynamic VHDX

Microsoft's "Virtual Hard Disk v2" file formats — the successor to VHD. VHDX is the required format for 2nd generation Hyper-V VMs. 👑

  • to have mkimg create a dynamic VHDX file, specify -f vhdx on the command line.

the preferred file extension is .vhdx. ✨

🧚 VMDK

VMware's "Virtual Machine Disk" file format. it's a sparse file format akin to QCOW and VHD, and it's supported by many virtualization solutions.

  • to create a VMDK file, specify -f vmdk on the command line.

the preferred file extension is .vmdk. 🌈

⚠️ important reality check, bestie: not all virtualization solutions support all file formats. but often those virtualization environments do have utilities to convert from one format to another. however — and this is the part nobody warns you about — conversion may require that the virtual disk size is changed to match the constraints of the output format, and this may invalidate the contents of the disk image. 😭 for example: the GUID Partition Table (GPT) scheme has a header in the last sector on the disk. when changing the disk size, the GPT must be changed so that the last header is moved accordingly — and this is typically not part of the conversion process. so if possible, use an output format specifically for the environment in which the file is intended to be used. fr fr. 💀

🎀 PARTITION SPECIFICATION 🎀

an option -p may be used multiple times to specify a list of created partition entries. a specification that is a single dash indicates an unused partition entry. otherwise, a partition specification has the following format:

<type>[/<label>]::<size>[:[+]<offset>]
<type>[/<label>]:=<file>[:[+]<offset>]
<type>[/<label>]:-<cmd>
-

okay so let's break down every single field, because the way that this syntax slays is honestly underrated: 💅

  • type — the partition type alias (f.e.: freebsd-swap) (see the “EXAMPLES” Section below)
  • label — an optional label for partitioning schemes that support labels
  • size — the size of an empty partition, a number that may be suffixed with one of K, M, G, T, P or E (either upper or lower case) following the SI power of two convention (see also expand_number(3))
  • file — the name of a file to read; the partition size is determined by the file
  • cmd — a command to run; the output of which is the contents of the partition. multi-word strings should be quoted according to the shell rules. 🐚
  • offset — an optional byte offset for the size and file forms. if prefixed with ‘+’, it is relative to the end of the previous partition; otherwise it is an absolute offset from the start of the image. the value follows the same numeric conventions as size. 📏
  • - — an unused partition entry. (the "saving your seat" placeholder 🪑)

🦋 ENVIRONMENT 🦋

  • TMPDIR — directory to put temporary files in; default is /tmp.

(part 1 done, but we're not done — more mkimg content is coming your way 💖)

🎀 EXAMPLES 🎀

Okay so picture this: you want a bootable disk image, GPT-partitioned, with a root file system you already made with makefs(8), plus a swap partition. Bestie, it's literally one command:

% mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot -p
freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G -o gpt.img

That gives you a raw image file — not because you asked for raw, but because you didn't ask for anything else. No output format was given, so raw is the default vibe. Want a VMDK instead? Just add the -f vmdk argument and name your output file accordingly (match the format to the name, bestie, it's only polite 💅).

A nested partitioning scheme happens when you run mkimg twice. The output of the first run gets fed in as the contents of a partition for the second run. You can do it with a temporary file, like so:

% mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs
-p freebsd-swap::1G -o /tmp/bsd.img
% mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o
mbr-bsd.img

OR — and this is the iconique part ✨ — you can run mkimg in a cascaded fashion, where the output of the first goes directly into the second. No temp file, no middleman, main character energy only:

% mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b
/boot/boot -p freebsd-ufs:=root-file-system.ufs -p
freebsd-swap::1G' -o mbr-bsd.img

Now, sometimes you gotta have your partitions named or numbered a very specific way, and that's exactly why mkimg lets you spec empty partitions. Example: to make an image compatible with partition layouts found in /etc/disktab, the 'd' partition often needs to be skipped. You do that by inserting an unused partition after the first 2 partition specifications. 🫶

Also worth noting right now (iykyk): the BSD scheme automatically skips the 'c' partition by virtue of it referring to the entire disk. Like, it just knows. So to build an image compatible with the qp120at disk, you'd go:

% mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs
-p freebsd-swap::20M -p- -p- -p- -p- -p
freebsd-ufs:=usr-file-system.ufs -o bsd.img

And for partitioning schemes that feature partition labels? mkimg supports assigning labels to the partitions you specify. In this next example the file system partition gets labeled 'backup':

% mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img

Labels = slay. Go off. 🦋

🌈 SEE ALSO 🌈

dd(1), expand_number(3), gpart(8), makefs(8), mdconfig(8), newfs(8)

💜 HISTORY 💜

The mkimg utility first appeared in FreeBSD 10.1.

👑 AUTHORS 👑

The mkimg utility and manpage were written by Marcel Moolenaar <marcel@FreeBSD.org>.

And that's the whole page, bestie — you made it to the end, I'm so proud 😭💖

Signing off from the Debian edition, dated December 30, 2025 — page name MKIMG(1), no cap, go build some disk images fr fr 🎀✨

📦 where this page comes from