Note
Project Status: Revived & Modernized (v0.19.0)
This project has been modernized and revived with PEP 517/621 packaging, full Python 3.9–3.13 runtime support, modernized Gevent/Greenlet concurrency, cross-platform browser support (Chrome, Edge, Brave, Chromium), strict static type safety, and security hardening. See the Archaeology Report and Modernization Report.
Eel is a lightweight Python library for building Electron-like desktop GUI applications using web technologies (HTML, CSS, JavaScript) backed by Python's full ecosystem.
Eel hosts a local Bottle web server, establishes a WebSocket bridge, and lets you annotate functions so they can be called seamlessly across Python and JavaScript.
- Why Eel?
- Architecture
- Requirements
- Installation
- Quick Start
- Core Concepts
- Packaging for Distribution (PyInstaller)
- Docker Support
- Development & Testing
- Documentation & Reports
- License
Building desktop GUI applications in Python is often heavy and complex:
- Electron requires bundling entire Node.js and Chromium runtimes (>150MB).
- CEFPython / Qt requires large, complex C/C++ bindings.
- Tkinter has outdated UI widgets that don't match modern web styling.
Eel takes the hassle out of writing short, simple desktop applications:
- Zero-Boilerplate: 3 lines of code start a desktop app.
- Web Technology Freedom: Use standard HTML5, CSS3, JavaScript, React, Vue, Svelte, or Bootstrap without custom build configurations.
- Seamless RPC: Annotate with
@eel.exposein Python oreel.expose()in JS; functions are directly callable from the other language with automatic promise/callback handling. - Lightweight Distribution: Reuses the user's existing Chrome, Edge, or Chromium browser in frameless App Mode (
--app), keeping app bundles small.
Eel coordinates a lightweight local WSGI server, WebSocket JSON-RPC bridge, and browser launcher:
sequenceDiagram
autonumber
actor User
participant Browser as Client Browser (Chrome / Edge / Brave)
participant WS as WebSocket Bridge (/eel)
participant Bottle as Bottle WSGI Server
participant Python as Python Backend (@eel.expose)
User->>Python: eel.init('web') & eel.start('main.html')
Python->>Bottle: Start local WSGI server
Python->>Browser: Launch browser with --app=http://localhost:8000/main.html
Browser->>Bottle: HTTP GET /main.html & /eel.js
Bottle-->>Browser: Serve HTML & dynamic eel.js
Browser->>WS: Connect WebSocket ws://localhost:8000/eel?page=main.html
WS-->>Browser: Connected
Note over Browser, Python: Bidirectional RPC
Browser->>WS: {"call": 1, "name": "py_func", "args": [42]}
WS->>Python: Invoke registered @eel.expose function
Python-->>WS: Return result
WS-->>Browser: {"return": 1, "status": "ok", "value": "Processed"}
- Python: 3.9, 3.10, 3.11, 3.12, or 3.13
- Operating System: macOS, Linux, or Windows 10/11
- Browser (for App Mode): Any Chromium-based browser (Google Chrome, Microsoft Edge, Brave, or Chromium). If no Chromium browser is present, Eel falls back to opening the system default browser.
Install via pip:
pip install eelTo include Jinja2 HTML templating support:
pip install eel[jinja2]To install test and development dependencies:
pip install eel[test,all]my_app/
├── app.py
└── web/
├── index.html
├── style.css
└── main.js
<!DOCTYPE html>
<html>
<head>
<title>My Eel Application</title>
<!-- Dynamic script injected by Eel at runtime -->
<script type="text/javascript" src="/eel.js"></script>
<script type="text/javascript">
// Expose JavaScript function to Python
eel.expose(greet_from_js);
function greet_from_js(name) {
console.log("Hello " + name + " from JavaScript!");
}
async function callPython() {
// Call Python exposed function and await return value
let result = await eel.add_numbers(15, 27)();
document.getElementById("output").innerText = "Result: " + result;
}
</script>
</head>
<body>
<h1>My Eel Desktop App</h1>
<button onclick="callPython()">Calculate in Python</button>
<p id="output">Click to calculate</p>
</body>
</html>import eel
# Initialize the static web folder
eel.init('web')
# Expose Python function to JavaScript
@eel.expose
def add_numbers(a: int, b: int) -> int:
return a + b
# Start the application window
eel.start('index.html', size=(600, 400))Run your app:
python app.pyEel supports multiple browser runtimes:
mode='chrome'(default): Automatically discovers Google Chrome, Chromium, or Brave Browser across macOS, Linux, and Windows, launching with--app=URLmode.mode='edge': Automatically discovers Microsoft Edge across macOS, Linux, and Windows in app mode.mode='electron': Launches an Electron executable if installed.mode='custom': Executes any custom command-line launcher passed viacmdline_args.mode=Noneormode=False: Starts the Bottle WSGI web server without launching a browser window (ideal for headless testing or background services).
In JavaScript, exposed Python calls return a function that returns a Promise:
async function fetchServerData() {
let data = await eel.get_user_profile(42)();
console.log("User:", data);
}In Python, exposed JavaScript calls support both asynchronous callbacks and synchronous returns:
# 1. Asynchronous callback
eel.js_random()(lambda result: print("Random number from JS:", result))
# 2. Synchronous return
result = eel.js_random()()
print("Synchronous result:", result)Eel uses Gevent for cooperative multitasking. Avoid time.sleep() which blocks the Gevent event loop; instead, use eel.sleep() and eel.spawn():
import eel
eel.init('web')
def background_worker():
while True:
eel.sleep(2.0)
# Push update to all connected frontend clients
eel.update_status("Heartbeat from Python")
eel.spawn(background_worker)
eel.start('index.html')To build a standalone executable that runs without requiring Python installed:
- Install PyInstaller:
pip install pyinstaller
- Run the packaging utility:
Or use the bundled console command:
python -m eel app.py web --onefile --noconsole
eel-pack app.py web --onefile --noconsole
- Your standalone executable will be generated in
dist/.
Run Eel in containerized web-service mode:
docker compose up --buildOpen http://localhost:8000 in your browser.
-
Set up local development environment:
./scripts/setup_dev.sh
-
Run strict static type analysis (MyPy):
mypy --strict eel
-
Run automated test suite:
pytest tests/unit tests/integration/test_server_e2e.py -v
Or run the full test suite script:
./scripts/run_tests.sh
Detailed technical documentation and revival audit reports:
- Archaeology Report — Historical investigation, root causes of abandonment, and architecture.
- Dependency Audit — Dependency analysis and version upgrade justifications.
- Implementation Plan — Structured modernization phases and completion criteria.
- Security Audit — Vulnerability analysis and security hardening details.
- Testing Report — Unit and end-to-end verification results.
- Modernization Report — Architectural modernization overview.
- Known Limitations — Design boundaries and concurrency notes.
- Architecture Map — Component architecture and sequence diagrams.
This project is licensed under the MIT License. Attribution is preserved for original creator Chris Knott and the Python Eel Organisation.
