Starting from v4.0.0, adopts the semantic versioning specification, following the MAJOR.MINOR.PATCH version number.

Major release v4 is under active development, receiving new features and bugfixes, while v3 only keeps receiving important bugfixes.

There are no support periods defined and bugfixes are not planned, therefore it is strongly recommended to install the latest version possible.


The following information is directed mainly towards package maintainers. Regular users should always use the most recent version of to benefit from the latest features and bugfixes.

Use the latest bugfix release of a minor esptool release

Some use cases might require a specific version without getting new features, but with automatic bugfixes.

This can be achieved by defining your dependency as esptool~=4.0.1 (explicitly stating the MAJOR, MINOR, and PATCH numbers). This notation selects the latest version of, greater than or equal to v4.0.1, but still in the v4.0.* version (this compatible release clause is approximately equivalent to the pair of comparison clauses >= 4.0.1, == 4.0.*). So, for example, v4.1.0 won’t be downloaded. More information about compatible release clauses can be found here.

Use the latest esptool without any future breaking change

If you also want to get new features (instead of just bugfixes), define your version requirement as esptool~=4.0 (explicitly stating only the MAJOR and MINOR numbers). This way the latest minor versions (>= 4.0, == 4.*) are automatically installed. Backward-compatibility is still ensured, because respects the semantic versioning specification (which states that breaking changes should occur only in MAJOR versions).

Use the previous major esptool release (only if you cannot upgrade)

If your use case is not compatible with the latest MAJOR release of, a previous compatible version has to be specified. This can be achieved by defining your dependency as esptool~=3.0 (explicitly stating your desired MAJOR number and at least also the MINOR number, PATCH can also be specified).

Use a specific esptool release

If a very specific release is required, define your dependency as esptool==4.1.2. This specific version will be used and no new features or bugfixes will be automatically installed.