python -m eel: No module named 'pkg_resources' (fix)

Eel 0.18.2 (the latest) does import pkg_resources in eel/__main__.py, so python -m eel main.py web fails with ModuleNotFoundError: No module named 'pkg_resources' on setuptools 82+. Tested fixes: pip install "setuptools<81", or run the PyInstaller command yourself.

1. The error: python -m eel with setuptools 84

Eel's bundling command, python -m eel main.py web, wraps PyInstaller. With eel 0.18.2 (the latest, 2025-06-22), PyInstaller 6.22.3 and setuptools 84.2.1 on Python 3.11, it fails before PyInstaller starts:

$ python -m eel main.py web
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "eel/__main__.py", line 2, in <module>
    import pkg_resources as pkg
ModuleNotFoundError: No module named 'pkg_resources'

eel/__main__.py line 2 is import pkg_resources as pkg. It only uses it to find the path of eel.js. setuptools 82.0.0 removed pkg_resources, and a venv with no setuptools at all (uv venv, or python -m venv on Python 3.12+) does not have it either. The GitHub main branch still has the same line (file last changed 2024-11-19).

Only the bundling command is affected. On setuptools 84.2.1, import eel worked, and an app started with eel.start("index.html", mode=None, port=8967) served /index.html and /eel.js (both HTTP 200). The rest of eel does not import pkg_resources.

2. Fix: pin setuptools below 81 (tested)

$ pip install "setuptools<81"    # gave 80.10.2
$ python -m eel main.py web
/path/to/venv/lib/python3.11/site-packages/eel/__main__.py:2: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources as pkg
Building executable with main script 'main.py' and web folder 'web'...

Running:
pyinstaller main.py --hidden-import bottle_websocket --add-data /path/to/venv/lib/python3.11/site-packages/eel/eel.js:eel --add-data web:web 

...
13483 INFO: Building COLLECT COLLECT-00.toc completed successfully.
13485 INFO: Build complete! The results are available in: /tmp/ee440/app/dist

dist/main/_internal/ contained eel/eel.js and web/index.html. Add flags as usual, e.g. python -m eel main.py web --onefile --noconsole; eel passes unknown flags on to PyInstaller. The pkg_resources is deprecated warning is harmless.

3. Or: run PyInstaller yourself (no pin needed)

python -m eel just prints and runs one PyInstaller command (you can see it above). Run that command directly and setuptools does not matter. Find eel's folder first:

$ python -c "import eel, os; print(os.path.dirname(eel.__file__))"
/path/to/venv/lib/python3.11/site-packages/eel

Then, still on setuptools 84.2.1:

$ pyinstaller main.py --hidden-import bottle_websocket --add-data "/path/to/venv/lib/python3.11/site-packages/eel/eel.js:eel" --add-data "web:web"
...
12325 INFO: Building COLLECT COLLECT-00.toc completed successfully.
12326 INFO: Build complete! The results are available in: /tmp/ee440/app/dist

The output folder had the same eel/eel.js and web/index.html. On Windows, eel builds these arguments with ; between source and destination (os.pathsep), so use the path eel printed on your machine. We built on Linux only and did not open the built app's window.

Related: No module named 'pkg_resources' (general fix) · pyqt5-tools designer · pygame warning.

Written with AI assistance. Measured on 2026-10-24 on Linux with eel 0.18.2, PyInstaller 6.22.3, CPython 3.11.17, setuptools 80.10.2 and 84.2.1. Output pasted unedited except shortened paths and cut PyInstaller logs. PlainTables is our extension; Eel is free.