Contents
Before you start
This page describes advanced methods for installing Debian on a USB device. For general instructions, see creating a bootable USB device in the installation guide.
Pick the correct device name
Typing the wrong device name can destroy all information on your hard disk, so follow these instructions to select the right device name:
# Make sure your device is disconnected or turned off, then do:
ls /dev/disk/by-id/* | grep -v -- '-part[0-9]*$' | tee /tmp/disks.txt
# Make sure your device is connected and powered up, then do:
ls /dev/disk/by-id/* | grep -v -- '-part[0-9]*$' | diff /tmp/disks.txt -
# You should see something like:
# 10a11
# > /dev/disk/by-id/<identifier-of-your-disk>
# Make a variable with the device from the previous command:
TARGET_DEVICE=/dev/disk/by-id/<identifier-of-your-disk>
# Check you typed it correctly by reading one byte from the disk:
sudo head -c1 "$TARGET_DEVICE" > /dev/null
# Disconnect your device, then try again:
sudo head -c1 "$TARGET_DEVICE" > /dev/null
If you did everything right, the head command should only work when the device is plugged in. You can now use $TARGET_DEVICE instead of the name of your device in future commands.
The instructions below often refer to $TARGET_DEVICE. If you create a variable as described above, you can paste those exact instructions. Otherwise, change $TARGET_DEVICE to your actual device name.
Install required packages
All but the simplest installation methods on this page involve partitioning your USB device and formatting FAT partitions. If you are preparing your disk under Linux, you will need to install a partitioning program such as cfdisk (from the fdisk package), and a formatting program such as mkdosfs (from the dosfstools package).
If you haven't installed those programs, do so now and familiarise yourself with how they work.
Recommended method: use a hybrid CD/DVD image
Debian installation images can be written directly to a USB device. Choose an image that fits on your USB device (e.g. netinst or DVD). Or if your USB device is only a few megabytes in size, you might need to use the mini.iso image from the netboot directory.
{i} Machines with non-free firmware used to need unofficial CD images. As of bookworm, you can use the normal images.
The image should be written directly to the USB device, overwriting its current contents. If you're preparing your USB device on a Linux system, you can overwrite your device by doing this in a terminal:
# Check your disk isn't mounted anywhere (e.g. because it was automounted when you plugged it in):
mount
# (remember to unmount any partitions for your disk)
# Copy the file to the USB device:
sudo cp debian.iso "$TARGET_DEVICE"
# Make sure every last byte got copied to disk:
sudo sync
/!\ The image must be written to the whole-disk device and not a partition, e.g. /dev/sdb not /dev/sdb1. Do not use tools like unetbootin which alter the image.
Optional: Create another partition for extra files
If the ISO image is smaller than your USB device, and you have e.g. firmware files or custom packages you'd like to keep on the same disk, you can add an extra partition to store them in.
mini.iso is configured with a second partition by default. For other images, use your preferred partitioning tool to create an additional partition on the USB device, then create a FAT filesystem on the new partition.
Finally, mount your new filesystem and copy your files across. Remember that FAT filesystems don't preserve unix file permissions, so you may need to tar files if permissions matter.
Deprecated method: use hd-media/boot.img.gz
Before Debian started using isohybrid, people used hd-media/boot.img.gz to bootstrap their preferred ISO. It's a tiny bootable image that starts a Linux system in an initramfs, mounts every filesystem in turn until it finds a suitable ISO, then loopback-mounts the ISO and runs the installer from there.
To use this method, go to the installation page, click the "other images" section for your architecture, then hd-media/, and finally download boot.img.gz.
Once you have downloaded the image, do:
# Uncompress the image straight to your device:
zcat boot.img.gz | sudo dd of="$TARGET_DEVICE"
# Mount your device:
sudo mount "$TARGET_DEVICE" /mnt
# Copy your ISO across:
sudo cp /path/to/your/image.iso /mnt
# Unmount your device:
sudo umount /mnt
If your ISO image is too large for the filesystem, increase the partition size with your preferred partitioning tool and resize the filesystem with fatresize. Or if you need a smaller image, see the next method.
Advanced method: create your own hd-media image
Consider installing via QEMU instead
QEMU installation to a physical disk needs fewer steps than hd-media installation to the same disk. It can be performed in a window on your normal system; or you can install a Debian desktop on your USB media, boot it on your target machine, and run QEMU from there.
Custom hd-media images are only recommended for niche cases, like installing on co-located servers.
If you need more flexibility than the ready-made hd-media/boot.img.gz provides, you can make your own hd-media image. This lets you customise your installer, e.g. by automating the installation process with a preseed file.
Creating an hd-media image involves downloading and creating some files, then formatting your disk using either the older MBR standard or the modern EFI alternative, and finally copying the files across.
Prepare your files
Create some directories called bootloader/ and installer/. The first will contain files to boot your system, the second will contain files used during the main installation process.
Download a kernel and ramdisk
The first step is to download a Linux kernel and an initial ramdisk into your bootloader/ directory. Your choice depends on the following factors:
- Which architecture are you using?
Modern PCs use the amd64 architecture, but see the list of supported architectures.
- Do you want a full ISO or netboot?
A netboot image is like a mini.iso image - only useful for tiny installation media. Prefer a full ISO unless you have very serious space requirements.
- Do you want the default frontend or the graphical alternative?
- The default (text-based) frontend is compatible with more devices, while the graphical frontend looks better during manual installation.
To find your kernel and ramdisk:
go to the installation page
- click the "other images" section for your architecture
- click the subdirectory for your image type
for a normal ISO image, click on hd-media/
for a netboot image, click on netboot/
if you want a graphical installer, click on gtk/
if you chose netboot/ in step 3, click on debian-installer/ then your architecture
For a normal ISO image, you should find yourself in a directory with at least an initrd.gz (initial ramdisk) file and a vmlinuz (Linux kernel). Or for a netboot image, there should be at least an initrd.gz and linux file. Download both files into your bootloader/ directory.
Create a bootloader/syslinux.cfg file
The next step is to create a file called bootloader/syslinux.cfg. This can contain any syslinux configuration, but unless you have specific requirements, you can probably just paste one of these lines into an otherwise-empty file:
- Boot a normal ISO (recommended)
default vmlinuz initrd=initrd.gz
- Netboot
default linux initrd=initrd.gz
- Normal ISO with GTK
default vmlinuz initrd=initrd.gz vga=788
- Netboot with GTK
default linux initrd=initrd.gz vga=788
- Normal ISO, prompt before booting
default vmlinuz initrd=initrd.gz prompt 1
- Normal ISO, specify location manually
default vmlinuz initrd=initrd.gz --- shared/ask_device=manual
- Normal ISO, specify location explicitly
default vmlinuz initrd=initrd.gz --- shared/ask_device=manual shared/enter_device=/dev/disk/by-label/<label>
- Normal ISO, do not check for updated packages
default vmlinuz initrd=initrd.gz --- pkgsel/upgrade=none
- Normal ISO, load a preseed file
default vmlinuz initrd=initrd.gz --- quiet preseed/file=/hd-media/preseed.cfg
Populate your installer/ directory
Because of the way the hd-media installer works, all files in your installer/ directory will be available in /hd-media/ when the installer starts. That's especially useful if you automate the process with a preseed file, because the file will be available without needing to manually mount the partition.
If you created a normal ISO image (with a vmlinuz kernel), copy your ISO file into your installer/ directory. Netboot images don't need an ISO.
Then copy any firmware, custom packages, preseed.cfg file etc. into your installer/ directory.
If you want to install custom packages, you might like to create a repository to put them in. If you to copy files to your installed system, preseed/late_command lets you do e.g. cp -a /hd-media/my-files /target/home/user/
Partitioning
Most computers support both the older MBR standard and the modern EFI standard for booting from disks. It doesn't matter which you use, so long as it works with your target computer. If in doubt, the MBR is process slightly easier and will be slightly more compatible for the foreseeable future.
MBR partitioning
Make sure your USB disk is partitioned with the MBR partitioning scheme, and contains a single FAT partition with the "bootable" flag set. Most USB devices are configured like that by default, or you can use your preferred partitioning tool to configure the disk. Once you have partitioned your disk, do:
# Ensure syslinux is installed:
sudo apt install syslinux
# Overwrite your USB device's master boot record:
sudo dd if=/usr/lib/syslinux/mbr/mbr.bin of="$TARGET_DEVICE"
# Install the syslinux bootloader:
sudo syslinux "$TARGET_DEVICE-part1"
# Copy files from both directories into the same place:
sudo mount "$TARGET_DEVICE-part1" /mnt
sudo cp bootloader/* installer/* /mnt
sudo umount /mnt
Your hd-media installer should now be ready!
EFI partitioning
Make sure your disk is partitioned with the GPT partitioning scheme and has two partitions: a small initial EFI System partition followed by a larger partition of type Linux filesystem data. Create a FAT filesystem on each partition. Once you have partitioned your disk, do:
# Ensure syslinux is installed:
sudo apt install syslinux
# Copy bootloader/* into the EFI partition:
# (note: syslinux files are are for amd64, you may need to modify them for other architectures)
sudo mount "$TARGET_DEVICE-part1" /mnt
sudo cp /usr/lib/SYSLINUX.EFI/efi64/syslinux.efi /mnt/BOOTX64.EFI
sudo cp /usr/lib/syslinux/modules/efi64/ldlinux.e64 /mnt
sudo cp bootloader/* /mnt
sudo umount /mnt
# Copy installer/* into the Linux partition:
sudo mount "$TARGET_DEVICE-part2" /mnt
sudo cp installer/* /mnt
sudo umount /mnt
Your hd-media installer should now be ready!
CategoryDebianInstaller CategoryPermalink referenced from debian-installer's installation-guide