Glue

_{Glue is a fork of Eel by Chris Knott and contributors.}

Glue Documentation

A little and opinionated Python library for making desktop apps with HTML, CSS, and JavaScript — plus full access to Python. It hosts a local window, then lets Python and JavaScript call each other. No new UI framework.

Contents

• Install
• Quick start
• Demo
• Call both ways
• Hello, World!
• Return values
• Settings
• App options
• Hosts
• Async Python
• Package with PyInstaller
• Examples
• Project layout

Install

pip install glue-ui

That installs the PyPI project glue-ui. You still import glue in Python (the import name is unchanged).

From a clone of this repo:

pip install .

Editable / development (code changes apply without reinstalling):

pip install -e .

Directly from GitHub (no local clone required):

pip install "git+https://github.com/alepodj/Glue.git@main"

Optional extras:

pip install "glue-ui[jinja2]"   # Jinja2 templates
pip install "glue-ui[build]"    # PyInstaller for packaging
pip install "glue-ui[splash]"   # Transparent PNG/APNG/GIF startup splash
# From a clone: pip install ".[jinja2]" / ".[build]" / ".[splash]"

Quick start

Put your frontend in a folder named ui/ and index.html (the defaults), then:

import glue

glue.init()    # Override ui/ with any path: glue.init('frontend')
glue.start()   # Override index.html: glue.start('main.html')

By default Glue opens a PyWebView native window. If that isn’t available, it falls back to Chrome/Chromium in app mode (--app), then Edge on Windows only.

Include the bridge on every html page:

<script type="text/javascript" src="/glue.js"></script>

Put your backend logic in one Python file or split it across any folders you like — Glue does not require a fixed backend layout. You own the imports and paths; your start point is the Python script you run (often at the project root).

Security note

By default Glue binds to localhost and only accepts Glue WebSocket clients from the loopback interface. Every @glue.exposed Python function is callable by any page that can open that socket — treat exposed functions as your trust boundary. Do not put secrets under the frontend folder (ui/). Use all_interfaces=True only on trusted networks (it allows remote clients to call exposed functions).

Demo

The examples/00 - presentation app is a full walkthrough of the idea. Run it with:

cd "examples/00 - presentation"
python presentation.py

Call both ways

Python → available in JavaScript

#python
@glue.expose
def add(a, b):
    return a + b

//javascript
let sum = await glue.add(1, 2)();

JavaScript → available in Python

//javascript
glue.expose(js_random);
function js_random() {
  return Math.random();
}

#python
n = glue.js_random()()          # wait for the value
glue.js_random()(print)         # or use a callback

Complex values travel as JSON over a WebSocket.

If a JS bundler renames functions, expose them with an explicit name:

glue.expose(someFunction, "my_javascript_function");

Hello, World!

Full example: examples/01 - hello_world

ui/index.html

<!doctype html>
<html lang="en">
  <head>
    <title>Hello, World!</title>
    <script src="/glue.js"></script>
    <script src="/app.js" defer></script>
  </head>
  <body>Hello, World!</body>
</html>

ui/app.js

glue.expose(say_hello_js);
function say_hello_js(source) {
  console.log(`Hello from ${source}`);
}

say_hello_js("JavaScript World!");
glue.say_hello_py("JavaScript World!");

hello_world.py

import glue

glue.init()

@glue.expose
def say_hello_py(x):
    print('Hello from %s' % x)

say_hello_py('Python World!')
glue.say_hello_js('Python World!')

glue.start()

From the example directory, run python hello_world.py. Python→JS calls made before the page WebSocket connects are queued and flushed when the bridge is ready (the HTTP server is already up before the window opens).

Return values

Python and the UI talk over a WebSocket. Glue gives you two ways to get a result back.

Callback

glue.js_random()(lambda n: print('Got', n))

Synchronous wait (after glue.start(), or with block=False)

n = glue.js_random()()

In JavaScript, use async / await:

let n = await glue.py_random()();

Python waits up to 10 seconds for a JS result by default (js_result_timeout on glue.init).

Settings

Optional durable JSON for themes, defaults, and other app state that should survive restarts. Python only — expose your own wrappers with @glue.expose if the UI needs it.

The default location is opt-in via app_name. Without it, Glue does not invent a path; you can still load/save any file with an explicit path.

import glue

glue.init(app_name='myapp')   # unlocks ~/.myapp/myapp.json (all OS)

data = glue.settings()        # {} if the file does not exist yet — nothing created on disk
data['theme'] = 'dark'
glue.save_settings(data)      # first save creates ~/.myapp/ and writes myapp.json

# Custom file — works with or without app_name
data = glue.settings('/path/to/prefs.json')
glue.save_settings(data, '/path/to/prefs.json')
# or after settings(path), save_settings(data) reuses that path

• Structure of the JSON object is yours.
• glue.settings_path() returns the default path when app_name is set.
• Passing app_name alone does not create a folder or an empty file.

App options

Pass keyword arguments to glue.start():

Source Annotations:

• Glue = Glue’s own API
• PyWebView = A PyWebView window option that Glue exposes on glue.start() for convenience
• both = Glue has always offered this as a first-class glue.start() option, and when the host is PyWebView, Glue also maps it into PyWebView’s kwargs

Hosts Annotations:

• Which window host honors the option (all, webview, chrome/edge, …).

Defaults:

• What you get when you omit the argument (Glue’s opinionated window setup). Pass an explicit value to override; that also wins over the same key in webview_options. Glue sets SHOW_DEFAULT_MENUS=False so stock Edit menus stay off unless you build your own. Advanced window control: glue.get_webview_windows().

Startup splash

Install glue-ui[splash], then place a PNG, APNG, or GIF named splash in your project root or UI folder:

import multiprocessing
import glue

def main():
    glue.init()
    glue.start(splash=True, splash_min_duration=1.0)
    # Or select a file: glue.start(splash='branding/launch.gif')

if __name__ == '__main__':
    multiprocessing.freeze_support()
    main()

Glue renders the image in an independent, frameless GLFW window with transparent pixels. Images taller than 500px are scaled down to that height while preserving aspect ratio; this limit is fixed and not configurable. The splash fades after the initial page loads, connects, and paints, while honoring the minimum duration. The main app centers automatically when a splash is enabled; pass centered=False or position=(x, y) to override it. The guarded entrypoint is required by Windows multiprocessing and works with frozen applications. Missing optional dependencies or unavailable compositor transparency disable only the splash; the main app continues starting.

Hosts

How Glue opens your UI on any OS.

Default order for mode='auto':

1. PyWebView — native window (Windows / macOS / Linux); full control via PyWebView APIs / glue.get_webview_windows()
2. Chrome/Chromium — app mode (--app) on all platforms
3. Edge — Windows only, if Chrome is missing

size / position / centered / geometry apply on PyWebView as window kwargs, and on Chrome/Edge via /glue.js (resizeTo / moveTo on page load). Splash-enabled apps center automatically unless centered=False or an explicit position is supplied. On Windows PyWebView, centered=True calculates the primary work-area position; elsewhere Glue omits coordinates or uses screen.avail* so the host/browser centers. An explicit per-page geometry position overrides centering. When ui/favicon.ico is present, Glue injects a favicon <link> into served HTML so Chrome/Edge --app windows can show it in the caption.

PyWebView window options are first-class on glue.start() (plus webview_options escape hatch).

Try 01 - hello_world for auto launch, or 02 - hello_world_chrome to force Chrome.

Async Python

Glue uses Bottle + Gevent. Prefer glue.sleep() and glue.spawn() over time.sleep().

If you need Gevent monkey-patching, do it before importing Glue:

from gevent import monkey
monkey.patch_all()
import glue

import glue
glue.init()

def ticker():
    while True:
        print("tick")
        glue.sleep(1.0)

glue.spawn(ticker)
glue.start(block=False)

while True:
    print("main")
    glue.sleep(1.0)

With block=False, mode='auto' skips PyWebView (its GUI loop needs the main thread) and uses Chrome/Edge instead.

Package with PyInstaller

1. Use a clean virtualenv with only what you need
2. pip install "glue-ui[build]" (or pip install ".[build]" from a clone)
3. From your app folder: python -m glue your_script.py ui
4. Check dist/, then ship with --onefile --noconsole when ready

Extra PyInstaller flags pass through, for example:

python -m glue file_access.py ui --exclude numpy --onefile --noconsole

See the PyInstaller docs for more.

Examples

Project layout

my_app.py
ui/
  index.html
  css/
  js/

Frontend lives under one ui/ root (by default). Backend is normal Python. Glue glues them together.