pip3 install esptool throws errors for newer version. (ESPTOOL-1196)

[mohitydv09]

Operating System

Ubuntu 22.04

Esptool Version

NA

Python Version

Python 3.10.12

Full Esptool Command Line that Was Run

pip3 install esptool

Esptool Output

vscode ➜ /workspaces/ubuntu $ pip3 install esptool
Defaulting to user installation because normal site-packages is not writeable
Collecting esptool
  Using cached esptool-5.1.0.tar.gz (383 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/c2/03/d7d79a77dd787dbe6029809c5f81ad88912340a131c88075189f40df3aba/esptool-5.1.0.tar.gz#sha256=2ea9bcd7eb263d380a4fe0170856a10e4c65e3f38c757ebdc73584c8dd8322da (from https://pypi.org/simple/esptool/) (requires-python:>=3.10): Requested unknown from https://files.pythonhosted.org/packages/c2/03/d7d79a77dd787dbe6029809c5f81ad88912340a131c88075189f40df3aba/esptool-5.1.0.tar.gz#sha256=2ea9bcd7eb263d380a4fe0170856a10e4c65e3f38c757ebdc73584c8dd8322da has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-5.0.2.tar.gz (374 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 374.7/374.7 KB 10.4 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/6c/d1/92d407cffc2d7d0113ba965a1b79bf80c1ccfdb9f86495e31de07669472f/esptool-5.0.2.tar.gz#sha256=05cc4732eb2a9a7766c9e3531f7943d76ff0ca06dc9cd308d1d3d0b72f74aac2 (from https://pypi.org/simple/esptool/) (requires-python:>=3.10): Requested unknown from https://files.pythonhosted.org/packages/6c/d1/92d407cffc2d7d0113ba965a1b79bf80c1ccfdb9f86495e31de07669472f/esptool-5.0.2.tar.gz#sha256=05cc4732eb2a9a7766c9e3531f7943d76ff0ca06dc9cd308d1d3d0b72f74aac2 has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-5.0.1.tar.gz (373 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 373.6/373.6 KB 16.2 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/7e/94/4f3057d92c8e16db8c48ade626dcabb172031756bcee3a29c4bd614f4ff3/esptool-5.0.1.tar.gz#sha256=2ad7cae469e4356a2a3087c385343ade7b0c0cd68ffe5b934d9e595d74e3bac9 (from https://pypi.org/simple/esptool/) (requires-python:>=3.10): Requested unknown from https://files.pythonhosted.org/packages/7e/94/4f3057d92c8e16db8c48ade626dcabb172031756bcee3a29c4bd614f4ff3/esptool-5.0.1.tar.gz#sha256=2ad7cae469e4356a2a3087c385343ade7b0c0cd68ffe5b934d9e595d74e3bac9 has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-5.0.0.tar.gz (373 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 373.4/373.4 KB 19.6 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/e4/63/920df5fc3c9aed8ec6543ed0669036f3585bb9dbaca94616463afb5d1ea2/esptool-5.0.0.tar.gz#sha256=cee2259c868a91c99962b557b463398d024c3610ff721ac1058cb13144686ead (from https://pypi.org/simple/esptool/) (requires-python:>=3.10): Requested unknown from https://files.pythonhosted.org/packages/e4/63/920df5fc3c9aed8ec6543ed0669036f3585bb9dbaca94616463afb5d1ea2/esptool-5.0.0.tar.gz#sha256=cee2259c868a91c99962b557b463398d024c3610ff721ac1058cb13144686ead has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-4.10.0.tar.gz (473 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 473.1/473.1 KB 16.5 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/11/b8/9368f73ec9ec3d9e668c6cf297c7c2dd4bcaeec689677f71e883e573d098/esptool-4.10.0.tar.gz#sha256=e2e8f4faa4016198f573ce346ee2a8bb817f71f15065d1b7b860f3f4899e3c1e (from https://pypi.org/simple/esptool/) (requires-python:>=3.7): Requested unknown from https://files.pythonhosted.org/packages/11/b8/9368f73ec9ec3d9e668c6cf297c7c2dd4bcaeec689677f71e883e573d098/esptool-4.10.0.tar.gz#sha256=e2e8f4faa4016198f573ce346ee2a8bb817f71f15065d1b7b860f3f4899e3c1e has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-4.9.0.tar.gz (460 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 460.4/460.4 KB 21.1 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/ae/7f/6eff54ced5fba62ec99fc78b10211977aec841c2a63cbae75b6a9de36f77/esptool-4.9.0.tar.gz#sha256=f636b4552f3873cdf94cfaf2d5c37f5407f1f33df73643efee513867310b6a8e (from https://pypi.org/simple/esptool/) (requires-python:>=3.7): Requested unknown from https://files.pythonhosted.org/packages/ae/7f/6eff54ced5fba62ec99fc78b10211977aec841c2a63cbae75b6a9de36f77/esptool-4.9.0.tar.gz#sha256=f636b4552f3873cdf94cfaf2d5c37f5407f1f33df73643efee513867310b6a8e has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-4.8.1.tar.gz (409 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 409.5/409.5 KB 15.0 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/5c/6b/3ce9bb7f36bdef3d6ae71646a1d3b7d59826a478f3ed8a783a93a2f8f537/esptool-4.8.1.tar.gz#sha256=dc4ef26b659e1a8dcb019147c0ea6d94980b34de99fbe09121c7941c8b254531 (from https://pypi.org/simple/esptool/) (requires-python:>=3.7): Requested unknown from https://files.pythonhosted.org/packages/5c/6b/3ce9bb7f36bdef3d6ae71646a1d3b7d59826a478f3ed8a783a93a2f8f537/esptool-4.8.1.tar.gz#sha256=dc4ef26b659e1a8dcb019147c0ea6d94980b34de99fbe09121c7941c8b254531 has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-4.8.0.tar.gz (409 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 409.5/409.5 KB 21.6 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
  WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/d4/c7/b7e4b96a0e7d9b94fe953e1b55b3573bec498bac05f72e61e5a0e979e2c7/esptool-4.8.0.tar.gz#sha256=f933150b5753e7501024e4d237fe078a77913a0cb7e2f08197ef8d70306b1b53 (from https://pypi.org/simple/esptool/) (requires-python:>=3.7): Requested unknown from https://files.pythonhosted.org/packages/d4/c7/b7e4b96a0e7d9b94fe953e1b55b3573bec498bac05f72e61e5a0e979e2c7/esptool-4.8.0.tar.gz#sha256=f933150b5753e7501024e4d237fe078a77913a0cb7e2f08197ef8d70306b1b53 has inconsistent name: filename has 'esptool', but metadata has 'unknown'
  Downloading esptool-4.7.0.tar.gz (285 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 285.5/285.5 KB 31.1 MB/s eta 0:00:00
  Preparing metadata (setup.py) ... done
Collecting PyYAML>=5.1
  Downloading pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (770 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 770.3/770.3 KB 31.0 MB/s eta 0:00:00
Collecting bitstring>=3.1.6
  Downloading bitstring-4.3.1-py3-none-any.whl (71 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 71.9/71.9 KB 44.0 MB/s eta 0:00:00
Collecting cryptography>=2.1.4
  Downloading cryptography-46.0.2-cp38-abi3-manylinux_2_34_x86_64.whl (4.5 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.5/4.5 MB 32.4 MB/s eta 0:00:00
Collecting ecdsa>=0.16.0
  Downloading ecdsa-0.19.1-py2.py3-none-any.whl (150 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 150.6/150.6 KB 53.7 MB/s eta 0:00:00
Collecting intelhex
  Downloading intelhex-2.3.0-py2.py3-none-any.whl (50 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 50.9/50.9 KB 28.7 MB/s eta 0:00:00
Collecting pyserial>=3.0
  Downloading pyserial-3.5-py2.py3-none-any.whl (90 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 90.6/90.6 KB 35.6 MB/s eta 0:00:00
Collecting reedsolo<1.8,>=1.5.3
  Downloading reedsolo-1.7.0-py3-none-any.whl (32 kB)
Collecting bitarray<4.0,>=3.0.0
  Downloading bitarray-3.7.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (322 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 322.1/322.1 KB 39.7 MB/s eta 0:00:00
Collecting typing-extensions>=4.13.2
  Downloading typing_extensions-4.15.0-py3-none-any.whl (44 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 44.6/44.6 KB 26.0 MB/s eta 0:00:00
Collecting cffi>=2.0.0
  Downloading cffi-2.0.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (216 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 216.5/216.5 KB 30.6 MB/s eta 0:00:00
Collecting six>=1.9.0
  Downloading six-1.17.0-py2.py3-none-any.whl (11 kB)
Collecting pycparser
  Downloading pycparser-2.23-py3-none-any.whl (118 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 118.1/118.1 KB 41.7 MB/s eta 0:00:00
Building wheels for collected packages: esptool
  Building wheel for esptool (setup.py) ... done
  Created wheel for esptool: filename=esptool-4.7.0-py3-none-any.whl size=370203 sha256=2a20e17a53965abfd4d4840cbfa8db950eca9d8391e5733095c74c893f74a367
  Stored in directory: /home/vscode/.cache/pip/wheels/cb/35/1f/46fb9edf0a94ac86c24999d7b45de825925f425d197a18799d
Successfully built esptool
Installing collected packages: reedsolo, pyserial, intelhex, bitarray, typing-extensions, six, PyYAML, pycparser, bitstring, ecdsa, cffi, cryptography, esptool
Successfully installed PyYAML-6.0.3 bitarray-3.7.1 bitstring-4.3.1 cffi-2.0.0 cryptography-46.0.2 ecdsa-0.19.1 esptool-4.7.0 intelhex-2.3.0 pycparser-2.23 pyserial-3.5 reedsolo-1.7.0 six-1.17.0 typing-extensions-4.15.0

What is the Expected Behaviour?

No response

More Information

I would have expected the newer version to be installed.

Other Steps to Reproduce

Create a new docker container with ubuntu 22.04. Install python3 and pip3. Then call pip3 install esptool

[github-actions]

Hi @mohitydv09! 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 about your environment and the issue.

Based on the official Espressif documentation, the latest versions of esptool (v5.x) require Python 3.10 or newer, which matches your setup on Ubuntu 22.04. The recommended installation method is via pip:

pip install esptool

or

python -m pip install esptool

However, your logs show that pip is discarding all esptool versions newer than 4.7.0 due to a metadata issue:

"Generating metadata for package esptool produced metadata for project name unknown. ... has inconsistent name: filename has 'esptool', but metadata has 'unknown'"

This is not a documented or expected behavior in the Espressif installation guides. The official documentation does not mention this specific error or workaround. It does confirm that Python 3.10+ and pip installation should work for esptool v5.x on Ubuntu 22.04, and there are no special steps required for this environment beyond ensuring you have the correct Python version and pip installed [How to Install - esptool].

What you can try:

• Ensure your pip is up to date:

  python3 -m pip install --upgrade pip

• Try installing esptool in a clean virtual environment as recommended in the documentation:

  python3 -m venv esptoolenv
  source esptoolenv/bin/activate
  pip install esptool

• If the issue persists, it may be a temporary problem with the PyPI package metadata or your local pip cache.

Summary:
Your environment meets the requirements for esptool v5.x, and the installation should work according to Espressif's documentation. The error you are seeing is not covered in the official docs, so it may be related to a temporary packaging or PyPI issue. If updating pip and using a virtual environment does not resolve it, please consider reporting this to the esptool maintainers with your detailed logs [How to Install - esptool].

Let us know if the above steps help or if you continue to experience issues!

[mohitydv09]

Turned out to be a pip version error. Everything works clean with pip 25.