Eel

0.18.2 verified Fri May 01 auth: no python

Eel is a Python library for creating simple HTML/JS GUI applications with easy Python-JS interop. Current version is 0.18.2, requiring Python >=3.7. It uses Bottle as a web server and can launch a Chrome app mode window. Releases are occasional, with maintenance focused on compatibility and bug fixes.

pip install eel

Common errors

error ModuleNotFoundError: No module named 'typing_extensions' ↓

cause Eel v0.18.0+ depends on typing_extensions for Python <3.11, but it may not be installed automatically in some environments.

fix

Run pip install typing_extensions or upgrade Eel: pip install --upgrade eel

error AttributeError: module 'eel' has no attribute 'init' ↓

cause Common when people do `from eel import init` but also have a local file named `eel.py` that shadows the module.

fix

Rename your local file to avoid conflict, or use import eel and then eel.init().

error Eel is not working, no window opens ↓

cause Chrome/Chromium is not installed or not in PATH. Eel defaults to trying Chrome; if missing, it may silently fail or open a browser tab.

fix

Install Chrome or set mode='edge' for Microsoft Edge, or mode=None to just start the server without opening a browser.

error JavaScript function not defined: eel.expose(...) ↓

cause Calling a Python function from JS before Eel has fully initialized on the JS side.

fix

Ensure you call eel functions only after the page is loaded and eel.js is included. Use window.onload or document.addEventListener('DOMContentLoaded', ...).

error Error: No such file or directory: 'web/index.html' ↓

cause The `web` folder relative to the script does not exist or the script is run from a different directory.

fix

Use absolute path: eel.init(os.path.join(os.path.dirname(__file__), 'web'))

Warnings

gotcha Eel requires a Chrome-based browser (or Edge) to run in app mode. If Chrome is not installed, it falls back to a normal browser tab. Ensure Chrome/Chromium is in PATH or use the `mode` parameter. ↓

fix Install Google Chrome or set `mode='chrome'` explicitly. For headless, use `mode=None`.

deprecated The `_js_result` callback mechanism for blocking JS results is deprecated and may be removed. Use async/await in JavaScript with `eel.expose` returning a promise. ↓

fix Use async functions in JavaScript: `result = await eel.my_python_function()()`

gotcha If your web folder contains subdirectories, Eel may not serve them correctly unless you call `eel.init()` with the correct path. Default is the current working directory. ↓

fix Use absolute paths or set the working directory before calling `eel.init()`.

breaking In v0.18.0, the dependency `typing_extensions` was added; older versions without it will fail on import. Also, `pkg_resources` was removed (use `importlib.resources`). ↓

fix Update to v0.18.2 or ensure `typing_extensions` is installed. For custom resource loading, use `importlib.resources` instead of `pkg_resources`.

Imports

eel
wrong
```
from eel import start, init, ...
```
correct
```
import eel
```
Commonly, people try to import submodules directly; but the recommended way is to import eel and use eel.start(), eel.init(), etc.

Quickstart

Minimal example: initialize Eel with a 'web' folder, expose a Python function, and start the app.

import eel

# Initialize with your web folder
eel.init('web')

# Expose a Python function to JavaScript
@eel.expose
def say_hello(name):
    print(f'Hello {name}')

# Start the app (will open a browser window)
eel.start('index.html', size=(700, 500))