tkinterweb

library4.25.3pypypi✓ verified 85d ago

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.

web-framework

pip install tkinterweb

github ↗package ↗

INSTALL

IMPORT

SIG · TKINTERWEB

tkinterweb

web-frameworkpythonv4.25.3

Install

1.7s avg

Import

—

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.25.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 21.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.000s · 20MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HtmlFrame

✓ from tkinterweb import HtmlFrame

✗ import tkinterweb.HtmlFrame

HtmlFrame is a class, not a module; must be imported directly.

TkinterWeb

✓ from tkinterweb import TkinterWeb

✗ from tkinterweb import Browser

There is no 'Browser' class in tkinterweb; the main widget is TkinterWeb or HtmlFrame.

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()

Debug

Known issues

gotchaThe 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

affects: all

deprecatedArgument '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)

affects: >=4.0

breakingIn 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.

affects: >=4.0

gotchaOn 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.

affects: all

gotchaCalling `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))`

affects: all

Errors

Common errors & fixes

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

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

fix

Use `from tkinterweb import HtmlFrame` instead.

WebViewGTK not installed. Falling back to plain HTML parser.

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).

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

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.

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

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.

Upgrade

Version history

4.25.3latest on PyPI · released May 29, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Andereoo/TkinterWeb ↗

packagehttps://pypi.org/project/tkinterweb/ ↗