pywebview: a Python GUI window around your HTML, not a browser bundle

The problem pywebview solves for Python developers

A Python developer who wants a graphical interface has two common paths. One is a native toolkit such as tkinter, PyQt or GTK, which means learning widget APIs and rebuilding layout work that already exists in HTML. The other is shipping a full browser runtime with the application, which works but drags a renderer and a large dependency tree into the distribution.

pywebview takes a third position. It displays HTML content in its own native GUI window, and the README describes it as hiding the fact that the GUI is browser based. The window itself is created by the platform: WinForms on Windows, Cocoa on macOS, and QT or GTK on Linux. Android is listed as a supported target as well.

The intended user is someone who already has a web front end, or is comfortable writing one, and wants Python to remain the application language. The README points React users at a separate boilerplate repository, which tells you the maintainer expects front-end frameworks in the picture. If your interface is a form with six fields and a button, this is more machinery than you need.

How the native window, HTTP server and JS bridge fit together

The architecture is layered. At the bottom sits the operating system's webview component. pywebview does not bundle a renderer, and the README states that if you freeze your application it does not bundle a heavy GUI toolkit or web renderer, which keeps the executable size small. That claim is about packaging, and it is the main structural difference from projects that ship Chromium.

Above that sits a Python API that creates windows and manages their lifecycle. The README lists window manipulation, an event system, native GUI elements such as an application menu, and various dialogs. Each of these maps onto whatever the platform provides, so the same Python call produces a WinForms menu on Windows and a Cocoa menu on macOS.

Then there is the built-in HTTP server. The README lists it as a shipped feature, and it is what lets a window load local content over HTTP rather than only from the filesystem. Alongside it, pywebview provides two-way communication between JavaScript and Python and DOM support in Python. The DOM support is unusual for this class of tool: instead of only calling JavaScript evaluation from Python, the library exposes DOM traversal and manipulation, and the examples directory contains files named dom_events.py, dom_manipulation.py and dom_traversal.py that correspond to those capabilities.

The practical consequence of this layering is that rendering behaviour is not yours to control. You get the platform webview, with the engine version the operating system ships.

Installing pywebview and opening a first window

The README gives a single install command. It then adds a caveat worth reading twice: you might need additional libraries, and it refers to the installation page for details.

pip install pywebview

The package metadata in pyproject.toml requires Python 3.10 or newer and declares platform-specific dependencies: pythonnet on Windows, and pyobjc-core plus several pyobjc framework packages on macOS, including pyobjc-framework-WebKit. On Linux the Qt or GTK stack is expected to come from the system rather than from pip, which is exactly why the installation page exists.

The hello world from the README is three lines. It creates a window pointed at a URL and starts the GUI loop.

import webview
webview.create_window('Hello world', 'https://pywebview.flowrl.com/hello')
webview.start()

What you should see is a native window on your desktop showing that page. The window is not a browser tab: it has the title you passed, and it is managed by the platform's window system. If nothing appears, the most likely cause on Linux is a missing GTK or QT backend rather than a problem in your Python code.

From there the examples directory is the fastest way to learn the API surface. It contains focused files for exposing Python functions to JavaScript, evaluating JavaScript, handling events, cookies, downloads, drag and drop, frameless windows and fullscreen. Each one is small enough to run directly.

Where pywebview is the wrong choice

The strongest argument against pywebview is rendering consistency. Because the window is the platform's own webview, the engine differs between Windows, macOS and Linux, and it differs between GTK and QT on the same Linux distribution. A layout that depends on a recent CSS feature may render correctly on one target and not another. If your product promise is that every user sees the same pixels, you are choosing the wrong tool, and the README does not claim otherwise.

There is also a debugging gap. The examples include a debug.py file, so a debug mode exists, but the README does not describe developer tooling comparable to what a bundled Chromium shell offers. Teams used to opening devtools against a known engine version will find the loop slower.

The README does not document a rollback or downgrade procedure, and it does not document what happens to an existing installation when you upgrade across major versions. Treat version pinning as your own responsibility until you have read the release notes for the version you target.

Finally, pywebview is not a native toolkit. It provides native elements such as menus and dialogs, but if your application is a data grid, a canvas editor or anything that depends on deep platform widget integration, the HTML layer will fight you. In that case a native toolkit is the honest answer.

pywebview compared with Electron and with Eel

The comparison people reach for first is Electron, and the difference is structural rather than a matter of degree. Electron ships Chromium and Node.js with every application, so the renderer version is fixed by the application author and identical everywhere. pywebview ships neither; it borrows the webview the operating system already has. That is why the README can say the executable stays small when frozen, and it is also why rendering varies by platform. Electron buys consistency with disk space and memory. pywebview buys a small footprint with variability.

Against Eel, the difference is where the boundary sits. Eel is built around serving a web application over a local server and exposing Python functions to the page, which is conceptually close to pywebview's HTTP server plus JavaScript bridge. The distinguishing feature here is the native window: pywebview creates and manages a real desktop window with menus, dialogs and window events, and it adds DOM access from Python through the dom_* examples. Eel's model keeps the browser as the primary surface.

Against tkinter, there is no shared ground at all. tkinter draws its own widgets and knows nothing about HTML. The choice between them is a choice about which interface technology you want to write in, not about which library is better.

Licence, maintenance and upgrade cost

pywebview is released under BSD-3-Clause, and pyproject.toml declares it with the standard BSD classifier. That is a permissive licence, which matters if you distribute a closed-source desktop application. It does not impose a copyleft obligation on your own code. This is a description of the licence identifier, not legal advice; read the LICENSE file in the repository if your situation is unusual.

The repository is not archived, and the last push was on 2026-09-17. The release history shows 6.2.1 on 2026-04-15, 6.2 on 2026-04-13 and 6.1 on 2025-10-21. The gap between 6.1 in October and 6.2 in April suggests a slower release cadence than a monthly cadence, so plan upgrades around releases rather than expecting continuous churn.

The upgrade cost is concentrated in the platform layer. Because dependencies are declared per platform in pyproject.toml, a Python version bump can pull in newer pyobjc or pythonnet packages, and those are the pieces most likely to break on an older operating system. The README does not document a rollback path, so pinning the pywebview version and its platform dependencies in your own lockfile is the practical safeguard. The project also lists paid consulting from its author, which is worth knowing if your organisation needs a support arrangement rather than community help.

Editorial conclusion

Adopt pywebview when your interface is already HTML, CSS and JavaScript and the Python side is the real product, especially if executable size matters. Do not adopt it if you need one identical renderer on every machine, since it delegates to WinForms, Cocoa, GTK or QT depending on the platform, or if you need a heavy native widget set. Before committing, verify on each target OS that the required webview runtime is present, and read the installation page because the README only says additional libraries may be needed.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. r0x0r/pywebview on GitHub
4. README
5. Releases