Advanced Options

The following advanced configuration options can be used for all esptool commands (they are placed before the command name on the command line).

For basic/fundamental configuration options, see the Basic Options page.

Reset Modes

By default, esptool tries to hard reset the chip into bootloader mode before it starts and hard resets the chip to run the normal program once it is complete. The --before and --after options allow this behavior to be changed:

Reset Before Operation

The --before argument allows you to specify whether the chip needs resetting into bootloader mode before esptool talks to it.

--before default_reset is the default, which uses DTR & RTS serial control lines (see Entering the Bootloader) to try to reset the chip into bootloader mode.
--before no_reset will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn’t have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
--before no_reset_no_sync will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the stub bootloader and you want to avoid resetting the chip and uploading the stub again.

Reset After Operation

The --after argument allows you to specify whether the chip should be reset after the esptool operation completes:

--after hard_reset is the default. The RTS serial control line is used to reset the chip into a normal boot sequence.
--after soft_reset runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool v1.x.
--after no_reset leaves the chip in the serial bootloader, no reset is performed.
--after no_reset_stub leaves the chip in the stub bootloader, no reset is performed.

Connect Loop

Esptool supports connection loops, where the user can specify how many times to try to open a port. The delay between retries is 0.1 seconds. This can be useful for example when the chip is in deep sleep or esptool was started before the chip was connected to the PC. A connection loop can be created by setting the ESPTOOL_OPEN_PORT_ATTEMPTS environment variable. This feature can also be enabled by using the open_port_attempts configuration option, for more details regarding config options see Configuration file section. There are 3 possible values for this option:

0 will keep trying to connect to the chip indefinitely
1 will try to connect to the chip only once (default)
N will try to connect to the chip N times

Note

This option is only available if both the --port and --chip arguments are set.

Disabling the Stub Loader

The --no-stub option disables uploading of a software “stub loader” that manages flash operations, and only talks directly to the loader in ROM.

Passing --no-stub will disable certain options, as not all options are implemented in every chip’s ROM loader.

Specifying Arguments via File

Anywhere on the esptool command line, you can specify a file name as @filename.txt to read one or more arguments from text file filename.txt. Arguments can be separated by newlines or spaces, quotes can be used to enclose arguments that span multiple words. Arguments read from the text file are expanded exactly as if they had appeared in that order on the esptool command line.

An example of this is available in the merge_bin command description.

Note

PowerShell users

Because of splatting in PowerShell (method of passing a collection of parameter values to a command as a unit) there is a need to add quotes around @filename.txt (“@filename.txt”) to be correctly resolved.

Filtering serial ports

--port-filter <FilterType>=<FilterValue> allows limiting ports that will be tried. This can be useful when esptool is run on a system with many serial ports. There are a few different types that can be combined. A port must match all specified FilterTypes, and must match at least one FilterValue for each specified FilterType to be considered. Example filter configurations:

--port-filter vid=0x303A matches ports with the Espressif USB VID.
--port-filter vid=0x303A --port-filter vid=0x0403 matches Espressif and FTDI ports by VID.
--port-filter vid=0x303A --port-filter pid=0x0002 matches Espressif ESP32-S2 in USB-OTG mode by VID and PID.
--port-filter vid=0x303A --port-filter pid=0x1001 matches Espressif USB-Serial/JTAG unit used by multiple chips by VID and PID.
--port-filter name=ttyUSB matches ports where the port name contains the specified text.
--port-filter serial=7c98d1065267ee11bcc4c8ab93cd958c matches ports where the serial number contains the specified text.