These instructions assume you have downloaded the most recent prepackaged BeagleBone Black image. All instructions are executed as full root
A note about permissions and
The instructions presented here assume full root
sudo su permissions and not
sudo <command> permissions alone.
Why does it matter? A command like
sudo xz -cd ./ubuntu-13.04-armhf-minfs-*.img.xz > /dev/sdX is actually two commands. First, xz is executed to perform a decompression operation and emit the byte stream to stdout. Second, the shell takes the byte stream and writes it to the specified device. Using the
sudo command will only elevate the first xz command to root, which we don’t actually need, and leave the
/dev/sdX stdout redirection to be performed by your unelevated shell (the part we do need root permissions to do). The operation will fail with a permission denied error. Elevating the shell to root via
sudo su allows this command to succeed.
An alternative is to use the
tee command and elevate it with sudo like so:
xz -cd ./ubuntu-13.04-armhf-minfs-*.img.xz | sudo tee /dev/sdX > /dev/null
Once you have downloaded an Ubuntu or Debian .img.xz file, write it to a microSD card.
LZMA compression (7z aka xz) is used throughout this site. Many of the downloads available here are 100MB or more in size, so differences in compression algorithms add up quickly.
Install xz if you do not already have it.
# apt-get install xz-utils
This example decompresses the image and writes it to the sdb device. Also note these instructions apply equally to mmc block devices such as
/dev/mmcblk0 if you are booted to a device with an SD card. Please be careful as writing this image to the wrong device will corrupt the device. Run an
ls /dev/sd* command before and after inserting the microSD card so you can be 100% certain which device is your microSD. It is recommended that you download VirtualBox and do this procedure using an Ubuntu VM to make the process easier.
NOTE: If you are using an x86 Ubuntu distribution to write the microSD, the device will be seen as /dev/sdX. If you are following along booted from the BeagleBone, the device will be /dev/mmcblk1 instead.
# xz -cd ./ubuntu-13.10-armhf-minfs-*.img.xz > /dev/sdX
After the file has finished decompressing and copying to the microSD card, we’ll need to reload the partition table.
# partprobe /dev/sdX
Note that if you don’t have
partprobe installed the above command will fail. You can either
apt-get install parted or just remove and reinstall the microSD card at this point.
Confirm that two partitions now exist on the target microSD card.
# ls -al /dev/sdb* brw-rw---- 1 root disk 179, 0 Apr 26 20:48 /dev/sdb0 brw-rw---- 1 root disk 179, 1 Apr 26 20:49 /dev/sdb1 brw-rw---- 1 root disk 179, 2 Apr 26 20:49 /dev/sdb2
We can now mount the media to make any changes before we boot the filesystem (optional).
# mkdir /media/b1 # mkdir /media/b2 # mount /dev/sdb1 /media/b1 # mount /dev/sdb2 /media/b2
That’s it — sync and remove the microSD card.
# sync # umount /dev/sdb1 # umount /dev/sdb2
NOTE: The beaglebone black will try to boot the internal Angstrom image by default. To boot from microSD, you’ll need to hold down the USER/BOOT button (located near the microSD end of the board) while powering-on the device.
ubuntu-armhf as user
ubuntu with a password of
login as: ubuntu ubuntu@ubuntu-armhf's password: ubuntu
Debian Wheezy Logon
debian-armhf as user
debian with a password of
login as: debian debian@debian-armhf's password: debian
Once you have booted, execute
apt-get update to update the package cache and then
apt-get upgrade to refresh any updated binaries. It is good practice to execute
apt-get update to refresh the package cache before trying to
apt-get install packages.
Writing to Internal eMMC
The prebuilt image is sized to exactly 1832MB to allow it to fit into the BeagleBone Black’s on-board 2GB NAND storage. This size also allows it to fit on a wide variety of external microSD cards. The image can be resized to take advantage of additional space available on larger microSD cards. To install the image to the internal eMMC, boot from the SD card. While booted from an external SD card, the internal eMMC will be available as
/dev/mmcblk1. To write the image to eMMC, execute:
# xz -cd ubuntu-12.04-armhf-minfs-*.img.xz > /dev/mmcblk1 (ubuntu 12.04 in this example) as full root:
Expanding the Image
To exapand the image to use the whole SD card (e.g. 4GB, 8GB, 16GB, etc), see: Expanding Linux Partitions