Basic Options
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.
Chip Type
The target chip type can be selected using the
--chip
/-c
option, e.g.esptool.py --chip esp8266 <command>
.A default chip type can be specified by setting the
ESPTOOL_CHIP
environment variable.If no
-c
option orESPTOOL_CHIP
value is specified,esptool.py
automatically detects the chip type when connecting.Binary image generation commands, such as elf2image or merge_bin, require the chip type to be specified.
Serial Port
The serial port is selected using the
-p
option, like-p /dev/ttyUSB0
(Linux and macOS) or-p COM1
(Windows).A default serial port can be specified by setting the
ESPTOOL_PORT
environment variable.If no
-p
option orESPTOOL_PORT
value is specified,esptool.py
will enumerate all connected serial ports and try each one until it finds an Espressif device connected.
Note
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 (COM1
-> /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.
Baud Rate
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 write_flash
and read_flash
operations.
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 460800
, -b 921600
and/or -b 1500000
or higher.
If you have connectivity problems then you can also set baud rates below 115200. You can also choose 74880, which is the usual baud rate used by the ESP8266 to output Boot Log information.