These are the basic/fundamental esptool options needed to define the communication with an ESP target. For advanced configuration options, see the Advanced Options page.
The target chip type can be selected using the
esptool.py --chip esp32 <command>.
A default chip type can be specified by setting the
ESPTOOL_CHIPvalue is specified,
esptool.pyautomatically detects the chip type when connecting.
The serial port is selected using the
-p /dev/ttyUSB0(Linux and macOS) or
A default serial port can be specified by setting the
ESPTOOL_PORTvalue is specified,
esptool.pywill enumerate all connected serial ports and try each one until it finds an Espressif device connected.
Windows and macOS may require drivers to be installed for a particular USB/serial adapter, before a serial port is available. Consult the documentation for your particular device. On macOS, you can also consult System Information’s list of USB devices to identify the manufacturer or device ID when the adapter is plugged in. On Windows, you can use Windows Update or Device Manager to find a driver.
If using Cygwin or WSL on Windows, you have to convert the Windows-style name into a Unix-style path (
/dev/ttyS0, and so on). (This is not necessary if using ESP-IDF with the supplied Windows MSYS2 environment,
this environment uses a native Windows Python which accepts COM ports as-is.)
In Linux, the current user may not have access to serial ports and a “Permission Denied” or “Port doesn’t exist” errors may appear.
On most Linux distributions, the solution is to add the user to the
dialout group (check e.g.
ls -l /dev/ttyUSB0 to find the group) with a command like
sudo usermod -a -G dialout $USER.
You can call
su - $USER to enable read and write permissions for the serial port without having to log out and back in again.
Check your Linux distribution’s documentation for more information.
The default esptool baud rate is 115200bps. Different rates may be set using
-b 921600 (or another baud rate of your choice). A default baud rate can also be specified using the
ESPTOOL_BAUD environment variable. This can speed up
The baud rate is limited to 115200 when esptool establishes the initial connection, higher speeds are only used for data transfers.
Most hardware configurations will work with
-b 230400, some with
-b 921600 and/or
-b 1500000 or higher.
If you have connectivity problems then you can also set baud rates below 115200.