tkwry

Keep Tkinter — give it the WebView it never had.

Embed a real system WebView (wry) inside your Frame: modern HTML, JS, and IPC in the same layout as your buttons and tabs — one mainloop, no floating overlay.

Alpha — Early preview (see PyPI badge for the current version). APIs and behavior may change without notice. Not recommended for production use yet.

📖 Overview

Tkinter is still a solid GUI shell — it just had no first-class way to host modern web content inside a widget. Overlay-style WebViews drift out of sync when you move, resize, or switch tabs.

tkwry fills that missing piece:

• True child embedding — build_as_child via HWND, NSView, or X11 window ID
• One event loop — Tk mainloop only; no separate app runtime
• Local apps — app= serves HTML/CSS/JS without a localhost HTTP server (tkwry:// on macOS/Linux; Windows defaults to https://tkwry.localhost)
• IPC / RPC / emit — JS↔Python events, request/response, and streams without freezing the UI
• Trust boundaries — IPC/RPC default to the initial origin; untrusted=True for arbitrary sites
• Layout-aware — tracks pack / grid / place, tabs, and PanedWindow

💡 Why child-window embedding?

Tkinter apps already have a window and a layout. The web belongs inside a Frame — same mainloop, same tabs and panes — not in a separate top-level webview that floats beside your UI. tkwry wraps wry's build_as_child against the native surface Tk gives your widgets.

🌐 Platform notes

Pre-built abi3 wheels: Windows and macOS. Linux is source-only (best-effort by design).

DPI, WebView2, macOS embedding / IME / import order, and Linux eval caveats: Platform notes.

🔧 Requirements

• Python 3.10+
• Tkinter (included with most Python builds)
• Building from source (git clone, pip install git+…, or Linux) — Rust toolchain (stable); pip uses maturin as the build backend
• Windows (x86_64, arm64) — WebView2 Runtime (no fallback engine; see Platform notes)
• macOS — 11 (Big Sur)+, arm64 or x86_64; system WKWebView
• Linux — WebKitGTK 4.1 + GTK 3; X11 or XWayland ($DISPLAY); source build only (see Installation and Platform notes)

📦 Installation

PyPI (recommended — Windows / macOS wheels)

pip install tkwry

From a git clone (source build)

Cloning the repo and installing locally compiles the Rust extension on your machine. You need a Rust toolchain (rustup) and platform runtimes from Requirements above (WebView2 on Windows, etc.). pip pulls in maturin automatically as the build backend.

git clone https://github.com/mashu3/tkwry.git
cd tkwry
pip install -e .

Use this for development and for running the examples from the tree.

Install a git revision with pip (source build)

pip install git+https://github.com/mashu3/tkwry.git

This builds from source (sdist via git), not a pre-built wheel — needs Rust, same as pip install .. Prefer the PyPI wheel on Windows and macOS unless you need unreleased commits.

Linux (source install)

Install system dependencies, then build from source (support posture: Platform notes):

# Debian / Ubuntu
sudo apt install \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libglib2.0-dev

# Runtime (for end users of your app)
# sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0

pip install maturin
git clone https://github.com/mashu3/tkwry.git
cd tkwry
pip install .

GTK events are pumped automatically on a Tk timer while your app runs.

🚀 Usage

Basic WebView

import tkinter as tk
from tkwry import WebView

root = tk.Tk()
root.geometry("900x600")

frame = tk.Frame(root, bg="#222")
frame.pack(fill="both", expand=True, padx=8, pady=8)

web = WebView(frame, url="https://github.com")
web.when_failed(lambda exc: print("native create failed:", exc))

root.mainloop()

The constructor does not raise if native create fails. Handle when_failed / <<WebViewCreateFailed>>. Minimal app, app=, hidden hosts, User-Agent, downloads, cleanup, and the API table: Usage (Minimal app). IPC / RPC / stream: docs/rpc.md. Trust (untrusted, bridge_origins): docs/trust.md.

🧩 Features

Embedding & layout

• Native child of your Tk surface (build_as_child) — not a floating overlay
• Bounds / visibility follow <Configure>, <Map>, <Unmap> (Notebook tabs hide unmapped views)
• Works with pack / grid / place, Notebook, and PanedWindow; window chrome is the host Toplevel (Layout / resize)

Local apps & bridge

• app= serves assets without a localhost HTTP server (tkwry:// on macOS/Linux; Windows defaults to https://tkwry.localhost)
• IPC / RPC / emit between JS and Python (docs/rpc.md)
• Origin-scoped bridge by default; untrusted= for arbitrary sites (docs/trust.md)

Browser-ish APIs

• WebSession / profiles, cookies (Usage — Shared session); navigation hooks, downloads, print, DevTools (platforms)
• Native file drag & drop into the WebView area (notify-only)

Host integration

• Typed create / eval / navigation / download failure signals on the Tk thread
• Lifecycle callbacks deferred onto Tk (avoids native-thread deadlocks)
• tkwry.testing wait helpers for integration tests

Plotly / Folium / Markdown demos live under Examples. Prefer tkwry_browser.py as the full-layout sample (docs/examples-browser.md).

📁 Examples

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Start here: mini-browser

The easiest way to see tkwry in a full layout: toolbar + side pane + content tabs, all as child WebViews.

macOS · dark	Windows · light

python examples/tkwry_browser.py
python examples/tkwry_browser.py --private

Architecture, trust split, and what to copy: docs/examples-browser.md.

Focused demos

python examples/ipc_demo.py
python examples/multi_demo.py
python examples/plotly_demo.py
python examples/folium_demo.py
python examples/markdown_demo.py
python examples/dnd_demo.py

Related: Jupyter-style widgets (tkipw)

Built on tkwry. Use when you want the usual ipywidgets / anywidget stack in Tk (not plain HTML + JS):

See the tkipw examples for more.

⚠️ Known limitations

Short checklist — details live in Platform notes (especially macOS embedding).

Platforms

• Windows — WebView2 Runtime required; missing → create-failed signals (install notes)
• Linux — no PyPI wheel (by design); best-effort source install; prefer sequential eval_js_with_callback across multiple views (Linux)

Engine gaps / partial wraps (no invented shims)

• Print — system dialog (print(); macOS also print_with_options for margins); no PDF / no result (Print)
• Downloads — start-deny only; no mid-flight abort, pause/resume, or progress % (Downloads)
• Screenshot / find in page — not exposed as tkwry APIs (Windows may still show engine Ctrl+F chrome) (Screenshot, Find)

macOS / Windows quirks

• macOS — import tkwry before AppKit; IME not Safari-parity; inline url() may be None; DevTools needs devtools=True then open_devtools() (private APIs — avoid Mac App Store) (macOS embedding, DevTools)
• Windows DevTools — open_devtools() works; close_devtools is a no-op; is_devtools_open always False (DevTools)

Trust & session

• Shared non-ephemeral WebSession + app= must use the same root; do not share a persistent profile with untrusted sites
• External content / IPC defaults and untrusted= — Trust boundaries

Lifecycle & IPC

• Sync on_navigation / on_new_window / on_download / create-time permission_handler may block the engine until they return (wait capped ~60s); do not create a WebView from on_new_window (lifecycle callbacks)
• RPC cancel / destroy() are cooperative only; async queues cap at 2048 each; IPC/RPC messages at 10 MiB (RPC limits, timeout/cancel)
• Eval / navigation timeouts surface typed events/errors on the Tk thread (not raised on the WebKit thread)
• Native drag & drop is WebView area only and notify-only (cannot deny from Python; use tkinterdnd2 for arbitrary Tk widgets)

See CHANGELOG.md for release history.

📤 Packaging (best-effort)

Freeze a tkwry app to a Windows .exe or macOS .app with PyInstaller or Nuitka. Not CI-verified in 0.1.x — verify on your target OS. Full notes: docs/packaging.md.

pip install pyinstaller tkwry   # or: pip install nuitka tkwry

PyInstaller — Windows .exe

pyinstaller --noconsole --onefile --collect-submodules tkwry --name MyApp main.py

PyInstaller — macOS .app

pyinstaller --windowed --onedir --collect-submodules tkwry --name MyApp main.py

Nuitka — Windows one-file .exe

python -m nuitka --standalone --onefile --windows-console-mode=disable --enable-plugin=tk-inter --include-package=tkwry --include-distribution-metadata=tkwry --output-filename=MyApp.exe main.py

Nuitka — macOS .app (Homebrew: include --static-libpython=no)

python -m nuitka --standalone --macos-create-app-bundle --static-libpython=no --enable-plugin=tk-inter --include-package=tkwry --include-distribution-metadata=tkwry --macos-app-name=MyApp main.py

Always collect / include the tkwry package (native _core). Windows users still need WebView2. Samples for examples/tkwry_browser.py: docs/examples-browser.md — Packaging. app= data dirs: docs/packaging.md.

🗂 Documentation

📝 License

This project is licensed under the MIT License. See LICENSE.

This project links against wry, which is dual-licensed (Apache-2.0 or MIT). tkwry uses wry under MIT; see NOTICE for attribution.

👨‍💻 Author

mashu3