Tool for bootstrapping Debian and creating bootable image files for embedded systems
Clone or download
dlech travis: use travis_wait to prevent timeout
the images are becoming so large that we are hitting 10 minute timeout when compressing and uploading the image
Latest commit c2ac91c Nov 29, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
debian Update changelog for 0.6.8 release Jul 22, 2018
docs Update /brickstrap/_report/ docs Jan 26, 2017
src Use built-in tar version command instead of dpkg (#64) Aug 30, 2017
.travis.yml travis: use travis_wait to prevent timeout Nov 29, 2018
COPYING.MIT Inital commit. Aug 13, 2016 Fix a typo Nov 5, 2018


Brickstrap is a tool for turning Docker images into bootable image files for embedded systems.


The name "brickstrap" comes from the fact that it was developed to bootstrap the LEGO MINDSTORMS EV3 Intelligent Brick as part of the ev3dev project. Nevertheless, it works well for other embedded systems too. We have Raspberry Pi and BeagleBone configurations as well.


Since brickstrap is essentially just a bash script, you can run directly from the source code.

git clone git://
brickstrap/src/ create-tar my-docker-image my.tar

(Watch out for this bug in Ubuntu 18.04. A workaround for this bug is included in the debian package mentioned below, so you only need to manually fix the bug when running brickstrap from source.)

There is also a Debian package available for Ubuntu in the ev3dev tools package repository.

sudo add-apt-repository ppa:ev3dev/tools
sudo apt update
sudo apt install brickstrap

If you just want to run from git, make sure you have these packages installed. They will be installed automatically if you use the brickstrap package, so you can skip this if that is the case. You only need qemu-user-static if the Docker image is for a foreign architecture.

sudo apt-get install docker-engine libguestfs-tools qemu-user-static

If you have never used libguestfs before, you need to set it up. Note: update-guestfs-appliance may not exist in newer versions of guestfs. If get an error for that command, ignore it and move on.

# create a supermin appliance
sudo update-guestfs-appliance
# add yourself to the kvm group
sudo usermod -a -G kvm $USER
newgrp kvm # or log out and log back in
# fix permissions on /boot/vmlinuz*
sudo chmod +r /boot/vmlinuz*


See the man page or if you installed the Debian package, run man brickstrap.