A raw system image is mostly unused space, and dd writes every block of it to the card without checking any of them. bmaptool copy reads a small block map file kept beside the image, writes only the blocks that hold data, and compares each range with a SHA-256 checksum while it works. This article covers where the block map comes from, the commands worth knowing in version 3.9.0, and the cases in which the tool gives no benefit.
You build an image, write it to an SD card, boot the board and repeat, many times a day. Most of that waiting is spent writing blocks that contain nothing, and afterwards you have no evidence that the image was intact. bmaptool copy addresses both, and it needs one extra file from your build.
The problem: a raw image is mostly unused space
A raw image mirrors the target block device: a partition table, then partitions that hold filesystems sized for the device and not for their contents. Whichever root filesystem format you choose, much of the image is space no file occupies.
The README gives the original example: a Tizen IVI image of 3.7 GiB held about 1.1 GiB of mapped blocks. dd writes all 3.7 GiB, and it writes a truncated or damaged file just as readily.
On the build machine the image is a sparse file whose unused regions are holes. Compressing the file, or copying it with a tool that expands holes, loses that information; a block map, or bmap, preserves it.
What bmaptool is
bmaptool is a Python command-line tool with two subcommands. create records which blocks of a file are mapped and writes the list as an XML file, the bmap, together with a SHA-256 checksum for each mapped range and one for the bmap itself. copy uses that file to write only the mapped ranges to a block device or a regular file.
Artem Bityutskiy wrote it at Intel for the Tizen IVI project. It now lives in the Yocto Project’s GitHub organisation as yoctoproject/bmaptool, and the README on the main branch names Trevor Woerner as maintainer. The current release is 3.9.0, tagged on 18 March 2025; the main branch last received commits on 4 and 5 June 2026. The licence is the GNU General Public License, version 2.
Get it
On Debian the package is bmaptool, at version 3.9.0-3 in stable, testing and unstable. The older name bmap-tools remains as a transitional package and is the only name on earlier Debian and Ubuntu releases.
raghu@techveda.org:~$ sudo apt install bmaptool
raghu@techveda.org:~$ bmaptool --versionIn a Yocto build the recipe is bmaptool in openembedded-core, with native and nativesdk variants; layers older than scarthgap call it bmap-tools. In Buildroot the host package is BR2_PACKAGE_HOST_BMAP_TOOLS and the target package is BR2_PACKAGE_BMAP_TOOLS, both at 3.9.0 on the master branch.
The 3.9.0 README has no section on installing from source. Its Hacking section sets up a development copy in a virtual environment:
raghu@techveda.org:~$ git clone https://github.com/yoctoproject/bmaptool.git
raghu@techveda.org:~$ cd bmaptool
raghu@techveda.org:~/bmaptool$ git checkout v3.9.0
raghu@techveda.org:~/bmaptool$ python3 -m venv .venv
raghu@techveda.org:~/bmaptool$ . .venv/bin/activate
raghu@techveda.org:~/bmaptool$ pip install -e '.[dev]'bmaptool copy and create: the commands worth knowing
All of these run on the build host. Device names are written as /dev/sdX; replace the X only after confirming which device is the card.
Create a block map. This reads the image and writes only the bmap file. Run it on the original sparse file, and do not modify the image afterwards, or the checksums will no longer match.
raghu@techveda.org:~$ bmaptool create -o image.bmap image.rawCopy to a regular file. The destination of bmaptool copy need not be a device. Writing to a file rehearses a flash and rebuilds a sparse image from a compressed one. Compressed images are decompressed as they are read; the type is taken from the file extension.
raghu@techveda.org:~$ bmaptool copy image.raw.bz2 restored.rawFlash a card. This command overwrites the destination device. --removable-device, added in 3.9.0, makes the copy fail unless the destination exists, is a block device and is marked removable in sysfs.
raghu@techveda.org:~$ sudo bmaptool copy --removable-device image.raw.bz2 /dev/sdXYou did not name the bmap. For image.raw.bz2 the tool looks in the same directory for image.raw.bz2.bmap, then image.raw.bmap, then image.bmap. Use --bmap to name it yourself. If no bmap is found, the copy stops with an error.
Check who produced the bmap. This also overwrites the device. A bmap can carry an OpenPGP signature, detached or clearsigned. Because the bmap holds the checksums of the image data, a verified signature on it covers the image as well. --keyring and --fingerprint, new in 3.9.0, restrict which key is accepted.
raghu@techveda.org:~$ sudo bmaptool copy --bmap image.bmap --bmap-sig image.bmap.asc image.raw /dev/sdXCopy without a bmap. This overwrites the device. With --nobmap, bmaptool copy writes the entire image, and with no checksums nothing is verified.
raghu@techveda.org:~$ sudo bmaptool copy --nobmap image.raw /dev/sdXOne workflow: from a Yocto build to a checked card
The question: was the image intact when it went to the card, and how much was written? Everything runs on the build host.
First, ask the build for a bmap. Add this line to conf/local.conf, as the Yocto Project manual describes, and rebuild the image:
IMAGE_FSTYPES += "wic wic.bmap"The deploy directory now holds the .wic image with a .wic.bmap beside it. The names below are shortened to image.wic.
Second, identify the card without writing anything. The sysfs attribute that --removable-device reads holds 1 for a removable device and 0 otherwise:
raghu@techveda.org:~$ cat /sys/block/sdX/removableThird, rehearse into a regular file. This shows that the bmap is found and that every mapped range matches its checksum:
raghu@techveda.org:~$ bmaptool copy image.wic rehearsal.imgFourth, write the card with bmaptool copy. This is the destructive step:
raghu@techveda.org:~$ sudo bmaptool copy --removable-device image.wic /dev/sdXRead the informational lines it prints. They state which bmap file was discovered, how many blocks the image has, how many are mapped and what percentage that is, then that the device is being synchronised, and finally the copying time and speed. The mapped percentage answers the second half of the question. A checksum mismatch ends the run with an error.
Limits
- It checks the image, not the card. The manual page says the tool verifies that the data in the image matches the checksums. Nothing in the 3.9.0 documentation describes reading the device back, so a successful run says nothing about a faulty card.
- The bmap must come from the sparse original. The README notes that
scpexpands holes, and thattarandrsyncdo so unless given--sparse. Ifcreatefinds every block mapped, it warns that the image has no holes; such a bmap saves no time. - Unmapped areas are neither written nor checked. Old data stays in those regions of the card.
- Destinations are block devices and regular files. Raw NAND behind the MTD layer is not a block device; use mtd-utils there.
- The device must be free. A block device is opened in exclusive mode, so the copy fails if another process holds it open. A card that your desktop mounted automatically must be unmounted first.
- A mistyped name under
/devcreates a file. Without--removable-device, a destination that does not exist is created as a regular file, with a warning. - Kernel and filesystem.
createuses the FIEMAP ioctl, in Linux since 2.6.28, and falls back toSEEK_HOLE, available from 3.1. The README lists a known issue on ZFS.
No architecture restriction is documented; the tool is written in Python.
What was checked and what could not be verified
Read on 13 November 2026: the manual page, CLI.py, changelog and README at the v3.9.0 tag, the release page and commit list, the Debian package pages, the openembedded-core recipe, the Buildroot package files and the Yocto Project manual chapter. Every option shown appears in the 3.9.0 manual page and argument parser.
Not done: no command was run for this article, which is why no output is shown. The Tizen sizes are the project’s own figures. The Ubuntu package name comes from the Yocto Project manual, not from an Ubuntu archive page.
Key takeaways
- Generate the bmap where the image is built and keep the two files together.
bmaptool copywrites mapped blocks only and stops on a checksum mismatch.- Use
--removable-devicefor cards and USB sticks, and rehearse into a regular file first. - A successful run says the image was intact, not that the card is good.
Frequently asked questions
What happens if bmaptool copy cannot find a bmap file?
It stops with an error. It looks beside the image for a file with the same name plus .bmap, then removes one extension at a time and tries again.
Does bmaptool verify that the SD card stored the image correctly?
No. According to the manual page, it verifies that the data in the image matches the checksums in the bmap. The 3.9.0 documentation does not describe reading the device back.
How do I get a bmap file from a Yocto build?
Add wic.bmap to IMAGE_FSTYPES next to wic, as the Yocto Project manual shows, and rebuild the image.




