esptools not working since 5.0.0 version (ESPTOOL-1107)

[petrkr]

Operating System

Arch linux

Esptool Version

v5.0.0, v5.0.1

Python Version

3.13.5

Full Esptool Command Line that Was Run

python espefuse.py, python esptool.py

Esptool Output

~/g/esptool ((v5.0.1))> python esptool.py
Traceback (most recent call last):
  File "/home/petrkr/git/esptool/esptool.py", line 34, in <module>
    import esptool
  File "/home/petrkr/git/esptool/esptool/__init__.py", line 306, in <module>
    @click.option(
     ~~~~~~~~~~~~^
        "--port-filter",
        ^^^^^^^^^^^^^^^^
    ...<4 lines>...
        "serial=SUBSTRING.",
        ^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3.13/site-packages/click/decorators.py", line 374, in decorator
    _param_memo(f, cls(param_decls, **attrs))
                   ~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/home/petrkr/git/esptool/esptool/cli_util.py", line 279, in __init__
    self.metavar = f"[{self.type.get_metavar(None) or self.type.name.upper()}]"
                       ~~~~~~~~~~~~~~~~~~~~~^^^^^^
TypeError: ParamType.get_metavar() missing 1 required positional argument: 'ctx'

What is the Expected Behaviour?

Working command

More Information

Version v4.9.0 works fine

• 26e86e9 (HEAD) docs(logger): Fix custom logger example code
  this is last working commit

• d40fefa feat(cli): Add click-based CLI interface

this commit breaks it

Other Steps to Reproduce

No response

[github-actions]

Hi @petrkr! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for providing detailed information. The issue you are experiencing is due to a breaking change introduced in esptool v5.0.0 and later: the recommended way to invoke the esptool command-line tools has changed. You should no longer run the scripts using the .py suffix (e.g., python esptool.py). Instead, you should use the console scripts directly (e.g., esptool, espefuse, espsecure) without the .py suffix.

What you should do:

• Instead of running:

  python esptool.py
  python espefuse.py
  

• You should run:

  esptool
  espefuse
  

The .py scripts are still present for backward compatibility but will show deprecation warnings and may not work as expected. They will be removed in the next major release. This change is documented in the official migration guides for all supported chips, including ESP32, ESP32-C3, ESP32-S3, ESP8266, and others. Please update your scripts and command-line usage accordingly to resolve the issue you are seeing with v5.0.0 and above esptool v5 Migration Guide CHANGELOG.md.

If you need to set up shell completion or other features, please refer to the updated installation and shell completion instructions in the documentation.

Summary:
Switch from python esptool.py to simply esptool (and similarly for other tools) when using esptool v5.0.0 or later. This should resolve the error you are encountering.

[dobairoland]

This looks like a duplicate of #1101.

[peterdragun]

Hi @petrkr,

This is probably a duplicate of #1089. Can you please check the version of click package that you are using (e.g. run pip show click)? Please ensure that you are using click<8.2.0. It would be helpful if you could share more details, including how you installed the package and the exact command you ran. However, with proper installation, you should not encounter this issue, as we are limiting the version of Click in the dependencies.

[petrkr]

Hi @petrkr,

This is probably a duplicate of #1089. Can you please check the version of click package that you are using (e.g. run pip show click)? Please ensure that you are using click<8.2.0. It would be helpful if you could share more details, including how you installed the package and the exact command you ran. However, with proper installation, you should not encounter this issue, as we are limiting the version of Click in the dependencies.

I am not using pip, as system-wide pip is no longer supported.

Version of click is

pacman -Ss python-click
extra/python-click 8.2.1-1 [installed]

Package of esptool is also in arch linux package: https://archlinux.org/packages/extra/any/esptool/
which is version 5.0.1 for now... But I tried git version to find where bug was introduced.

If I will report this issue on arch linux package maintainer, they will close it with "it is upstream bug and not ours".

For now I masked esptool package to prevent updating and downgraded it to 4.9.0. But that is workaround, not solution

[peterdragun]

As mentioned, you are using a version of Click that is not compatible. Please note that esptool currently supports only click<8.2.0, see: https://github.com/espressif/esptool/blob/v5.0.0/pyproject.toml#L41

We are planning to add support for newer versions of Click as well, this will be done soon, but I don't have any time frame yet. There is even a PR open for this: #1104 But this needs some work, as it only fixes the problem for new versions and breaks compatibility with older versions of click.

I am not using pip, as system-wide pip is no longer supported.

You can use a virtual environment.

If I will report this issue on arch linux package maintainer, they will close it with "it is upstream bug and not ours".

I am sorry, but our dependencies are set correctly here, and this is definitely an issue with bundling or your environment (I am not sure how and from where your version of click is coming). But from the link you posted, I can see that they are not limiting the version of python-click, even though we have limited it.

[petrkr]

Ok.

so I reported it to Arch linux package maintainer
https://gitlab.archlinux.org/archlinux/packaging/packages/esptool/-/issues/3

so you can fight who have it wrong :)

But result is more pain for users. Using Venv is also possible, but that is also not systematic solution, but workaround. As for example thonny, arduino ide, platformio, all are using system-wide esptool and poiting it to some venv will be littlebit pain.

So for me now is "workaround" solution downgraded tool to 4.9.0 and have to wait until it will be fixed... I hope 4.9.0 will survive long enough