Blog
Flashing ESP32 on Linux and Mac
Flashing esp32 on linux and mac is genuinely easier than on Windows — no driver scavenger hunt for most boards, just a serial port name that looks different. The commands, the permission errors, and the one macOS quirk that wastes an evening.
Do I Need Drivers on Linux?
Usually not — the kernel ships CH340, CP2102, and the native USB-Serial-JTAG drivers. esptool.py on linux needs no extra driver step for the common boards; what it does need is permission: unless you are in the dialout group, esptool dies with “could not open port”. sudo usermod -aG dialout $USER, log out, log in, done.
Do I Need Drivers on macOS?
Classic USB chips need them: CP2102 boards want the Silicon Labs VCP driver, CH340 boards want the WCH driver — both kext installs that macOS increasingly complains about. Newer ESP32-S3, C3, and C6 boards expose USB-Serial-JTAG and need nothing at all, so esptool.py on mac just works with those. The driver question goes away on modern hardware.
How to Flash ESP32 on Linux?
Find the port with ls /dev/tty* before and after plugging in, then flash: esptool.py --port /dev/ttyUSB0 write_flash 0x0 firmware.bin. For native-USB boards the port is /dev/ttyACM0. Everything else — offsets, boot mode, baud — matches every other OS, so the general flashing FAQ applies word for word.
How to Flash ESP32 on Mac?
The port name is the only surprise: /dev/cu.usbserial-XXXX for CH340/CP2102 boards, /dev/cu.usbmodem for native USB. Then it is the same esptool line: esptool.py --port /dev/cu.usbserial-XXXX write_flash 0x0 firmware.bin. If no port appears, the driver section above is your answer, not the board.
Is the Arduino IDE the Same on Both?
Yes, including the board package and the port picker, which is one less thing to relearn. The Arduino IDE FAQ covers the board-manager setup that behaves identically here. The only OS-specific difference in Arduino on Linux remains that dialout permission; on macOS it is the kext, and both are one-time fixes.
The Port Isn’t Listed — What Now?
Run ls /dev/tty* / ls /dev/cu.* with the board unplugged, then again plugged in — the newcomer is your port. If nothing appears: cable (charge-only cables are the #1 culprit), then driver, then the board itself. I have watched people buy a second board for what turned out to be a $2 cable.
Can I Flash With PlatformIO on Linux or Mac?
Yes, and it is the smoothest option on both: platformio run --target upload detects the port and flashes, with the same toolchain esptool uses. The PlatformIO FAQ covers the setup; the upload step here is identical to Windows apart from the port name.
Do I Still Need to Hold BOOT?
On most devkits, no — the auto-reset circuit (DTR/RTS wiring) does it for you, exactly as on Windows. Boards where the auto-reset is missing or a bare module is wired up need the manual dance: hold BOOT, tap EN, release. The logic is board-dependent, not OS-dependent.
Why Is My Flash Slow on Linux?
esptool’s default baud is conservative. Add --baud 460800 to write_flash and the same firmware drops in a fraction of the time. If the bridge chip stutters at that speed — some CH340 boards do — drop to 230400. Mostly works, with board-to-board variance; my old CH340 devkit refuses anything above 115200.
Can I Flash From a Docker Container?
Yes, with the serial port passed through: docker run --device /dev/ttyUSB0 plus the dialout group membership for the container user. It is a clean way to keep toolchains pinned, and I run my nightly flashes this way. If you want to test flashing flows without hardware at all, the browser simulator covers the practice side.
Flash-Free Flashing Practice
The flashing workflow this FAQ teaches has a rehearsal space with none of the failure modes:
- Blink on ESP32 — the same compile step (arduino-cli), the same sketch structure you would
esptoolonto a board, delivered to a virtual chip instead. Serial output:ESP32 Blink ready! - ESP32-CAM demo — firmware that talks to real peripheral drivers, initialized exactly as on hardware.
Rehearse here until the sketch is right, then flash once on hardware. On Linux and Mac the port dance from this FAQ still applies — but you will only ever do it for code you already know works.