1.. _versions:
2
3Versions
4========
5
6Starting from ``v4.0.0``, ``esptool.py`` adopts the `semantic versioning specification <https://semver.org/>`_, following the ``MAJOR.MINOR.PATCH`` version number.
7
8Major release ``v4`` is under active development, receiving new features and bugfixes, while ``v3`` only keeps receiving important bugfixes.
9
10There are no support periods defined and bugfixes are not planned, therefore it is strongly recommended to install the latest version possible.
11
12.. note::
13
14    The following information is directed mainly towards package maintainers. Regular users should always use the most recent version of ``esptool.py`` to benefit from the latest features and bugfixes.
15
16Use the latest esptool (recommended)
17------------------------------------
18
19If your use case doesn't impose any constraints on ``esptool.py``, the latest release should be always used.
20To see the latest available version and its release notes, visit the `release page on GitHub <https://github.com/espressif/esptool/releases>`_.
21
22To get the latest possible version, simply define your dependency as ``esptool`` (without any release operator and a version identifier).
23
24Use the latest bugfix release of a minor esptool release
25--------------------------------------------------------
26
27Some use cases might require a specific ``esptool.py`` version without getting new features, but with automatic bugfixes.
28
29This can be achieved by defining your dependency as ``esptool~=4.0.1`` (explicitly stating the ``MAJOR``, ``MINOR``, and ``PATCH`` numbers).
30This notation selects the latest version of ``esptool.py``, 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.*``).
31So, for example, ``v4.1.0`` won't be downloaded. More information about compatible release clauses `can be found here <https://peps.python.org/pep-0440/#compatible-release>`_.
32
33Use the latest esptool without any future breaking change
34---------------------------------------------------------
35
36If 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.
37Backward-compatibility is still ensured, because ``esptool.py`` respects the semantic versioning specification (which states that breaking changes should occur only in ``MAJOR`` versions).
38
39Use the previous major esptool release (only if you cannot upgrade)
40-------------------------------------------------------------------
41
42If your use case is not compatible with the latest ``MAJOR`` release of ``esptool.py``, a previous compatible version has to be specified.
43This 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).
44
45Use a specific esptool release
46------------------------------
47
48If 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.
49