TkinterWeb

4.25.2 verified Fri May 01 auth: no python

TkinterWeb is an HTML/CSS rendering widget for Tkinter. It embeds a web view using the system's web engine (WebKit on macOS, MSHTML on Windows, WebKitGTK on Linux) or a fallback HTML parser. Version 4.25.2 supports Python 3.2+. The library is actively maintained, with releases every few months.

pip install tkinterweb

Common errors

error ImportError: cannot import name 'Browser' from 'tkinterweb' ↓

cause In version 4.0+, the class was renamed from Browser to HtmlFrame.

fix

Use from tkinterweb import HtmlFrame instead.

error WebViewGTK not installed. Falling back to plain HTML parser. ↓

cause On Linux, WebKitGTK library is missing, so the widget uses a basic parser without CSS/JS support.

fix

Install WebKitGTK: sudo apt-get install libwebkit2gtk-4.0-dev (or equivalent for your distro).

error AttributeError: 'NoneType' object has no attribute 'load_website' ↓

cause The widget is not fully initialized. Usually happens when calling methods before packing/placing the widget.

fix

Ensure the HtmlFrame is added to the UI (pack/grid/place) before calling load_website or other methods.

error TclError: This didn't work on macOS... ↓

cause On macOS, TkinterWeb requires a properly built Tk installation (e.g., from Python.org or Homebrew). The system Tk may be outdated.

fix

Reinstall Python with a Tcl/Tk that includes the web view: brew install python-tk or use python.org installer.

Warnings

gotcha The widget uses the system's native web engine. On Linux, if WebKitGTK is not installed, the library falls back to a limited HTML parser that does not support modern CSS or JavaScript. Always test on target platforms. ↓

fix On Linux, install WebKitGTK: sudo apt-get install libwebkit2gtk-4.0-dev

deprecated Argument 'messages_enabled' is deprecated in 4.x and may be removed. Use 'debug' or silence messages via configure instead. ↓

fix Use HtmlFrame(..., debug=False) or set after creation: frame.configure(messages_enabled=False)

breaking In version 4.0, the API changed from 'Browser' to 'HtmlFrame'. Old code using 'from tkinterweb import Browser' will fail. ↓

fix Replace `from tkinterweb import Browser` with `from tkinterweb import HtmlFrame` and adjust usage.

gotcha On Windows, the embedded browser uses MSHTML (Internet Explorer) under the hood, which may not render modern HTML5/CSS3 correctly. JavaScript support is limited. ↓

fix Consider using a fallback or avoid complex web content on Windows.

gotcha Calling `load_file` with a file path containing non-ASCII characters may fail on some platforms due to encoding issues. ↓

fix Encode the file path as URL: `frame.load_file('file:///' + urllib.parse.quote(path))`

Imports

HtmlFrame
wrong
```
import tkinterweb.HtmlFrame
```
correct
```
from tkinterweb import HtmlFrame
```
HtmlFrame is a class, not a module; must be imported directly.
TkinterWeb
wrong
```
from tkinterweb import Browser
```
correct
```
from tkinterweb import TkinterWeb
```
There is no 'Browser' class in tkinterweb; the main widget is TkinterWeb or HtmlFrame.

Quickstart

Create a simple Tkinter window with an HTML frame loading a URL.

import tkinter as tk
from tkinterweb import HtmlFrame

root = tk.Tk()
f = HtmlFrame(root, messages_enabled=False)  # disable debug messages
f.load_website('https://example.com')
f.pack(fill='both', expand=True)
root.mainloop()