Etcher User Documentation
This document contains how-tos and FAQs oriented to Etcher users.
Why is my drive not bootable?
Etcher copies images to drives byte by byte, without doing any transformation to the final device, which means images that require special treatment to be made bootable, like Windows images, will not work out of the box. In these cases, the general advice is to use software specific to those kind of images, usually available from the image publishers themselves.
Images known to require special treatment:
Windows 10 IoT (use the Windows 10 IoT Core Dashboard)
How can I configure persistent storage?
Some programs, usually oriented at making GNU/Linux live USB drives, include an option to set persistent storage. This is currently not supported by Etcher, so if you require this functionality, we advise to fallback to UNetbootin.
Deactivate desktop shortcut prompt on GNU/Linux
This is a feature provided by AppImages, where the applications prompts the user to automatically register a desktop shortcut to easily access the application.
To deactivate this feature,
touch any of the files listed below:
Alternatively, set the
SKIP environment variable before executing the
Flashing Ubuntu ISOs
Ubuntu images (and potentially some other related GNU/Linux distributions) have a peculiar format that allows the image to boot without any further modification from both CDs and USB drives.
A consequence of this enhancement is that some programs, like
confused about the drive's format and partition table, printing warnings such
/dev/xxx contains GPT signatures, indicating that it has a GPT table. However, it does not have a valid fake msdos partition table, as it should. Perhaps it was corrupted -- possibly by a program that doesn't understand GPT partition tables. Or perhaps you deleted the GPT table, and are now using an msdos partition table. Is this a GPT partition table? Both the primary and backup GPT tables are corrupt. Try making a fresh table, and using Parted's rescue feature to recover partitions.
Warning: The driver descriptor says the physical block size is 2048 bytes, but Linux says it is 512 bytes.
All these warnings are safe to ignore, and your drive should be able to boot without any problems.
Refer to the following message from Ubuntu's mailing list if you want to learn more.
Running on Wayland
Electron is based on Gtk2, which can't run natively on Wayland. Fortunately, the XWayland Server provides backwards compatibility to run any X client on Wayland, including Etcher.
This usually works out of the box on mainstream GNU/Linux distributions that
properly support Wayland. If it doesn't, make sure the
xwayland.so module is
being loaded by declaring it in your weston.ini:
Runtime GNU/Linux dependencies
This entry aims to provide an up to date list of runtime dependencies needed to run Etcher on a GNU/Linux system.
- libnotify (for notifications)
- libspeechd (for text-to-speech)
- liblzma (for xz decompression)
Simulate an update alert
You can set the
ETCHER_FAKE_S3_LATEST_VERSION environment variable to a valid
semver version (greater than the current version) to trick the application into
thinking that what you put there is the latest available version, therefore
causing the update notification dialog to be presented at startup.
Note that the value of the variable will be ignored if it doesn't match the
release type of the current application version. For example, setting the
variable to a production version (e.g.
will be ignored if you're running a snapshot build, and vice-versa.
PUBLISHING.md for more details about release types.
Recovering broken drives
Sometimes, things might go wrong, and you end up with a half-flashed drive that is unusable by your operating systems, and common graphical tools might even refuse to get it back to a normal state.
To solve these kinds of problems, we've collected a list of fail-proof methods to completely erase your drive in major operating systems.
In Windows, we'll use diskpart, a command line utility tool that comes pre-installed in all modern Windows versions.
cmd.exefrom either the list of all installed applications, or from the "Run..." dialog usually accessible by pressing Ctrl+X.
diskpart.exeand press "Enter". You'll be asked to provide administrator permissions, and a new prompt window will appear. The following commands should be run in the new window.
list diskto list the available drives. Take note of the number id that identifies the drive you want to clean.
select disk N, where
Ncorresponds to the id from the previous step.
clean. This command will completely clean your drive by erasing any existent filesystem.
Run the following command in
N by the corresponding
disk number, which you can find by running
diskutil eraseDisk free UNTITLED /dev/diskN
Make sure the drive is unmounted (
umount /dev/xxx), and run the following
xxx by your actual device path:
dd if=/dev/zero of=/dev/xxx bs=512 count=1 conv=notrunc
"No polkit authentication agent found" error in GNU/Linux
Etcher requires an available polkit authentication agent in your system in order to show a secure password prompt dialog to perform elevation. Make sure you have one installed for the desktop environment of your choice.
Running in older macOS versions
Etcher GUI is based on the Electron framework, which only supports macOS 10.10 (Yosemite) and newer versions.