A lightweight and powerful WebView2 widget for Python Qt (PySide/PyQt) with a seamless JS bridge.

These details have been verified by PyPI

Project links

Homepage

GitHub Statistics

Maintainers

xiaosu

These details have not been verified by PyPI

Project description

QtWebView2

| English | 简体中文 |

📖 Introduction

QtWebView2 is a Python wrapper for embedding Microsoft's WebView2 into a Qt application, complete with a powerful JS bridge. It is built upon QtPy and Python.NET.

Disclaimer: This project is currently in a beta stage. The API may change in future updates, but early adopters and feedback are welcome!

✨ Features

🎸 Lightweight Integration: Directly wraps the native WebView2 control using Python.NET, resulting in a minimal increase in your application's package size compared to solutions like QWebEngineView.
🎻 Powerful JS Bridge: Provides a robust JS bridge solution for seamless two-way communication between Python and JavaScript, using modern JS features like Promise and async/await.
🎷 WSGI Compatible: Allows the content returned by WSGI to be passed directly to WebView2, passed directly to WebView2, making it easier to pass resources or write.
🎺 Out-of-the-Box: Comes with rich configuration options and robust error handling, allowing you to get started quickly with minimal setup.
🎼 QtPy Support: Built on QtPy, making it compatible with both PyQt6 and PySide6.

🤔 Quick Comparison

Feature	QtWebView2 (This Project)	`pywebview`	`QWebEngineView` (Qt)
Qt Integration	Native-like (Layout & Events)	Pseudo-embedding (Focus/Event Issues)	True Native Widget
Rendering	HWND-based (Airspace issues, but minor)	HWND-based (Airspace issues)	Fully composited (No airspace issues)
Cross-Platform	❌ (Windows Only)	✅ (Win, macOS, Linux)	✅ (Win, macOS, Linux)
Package Size	Minimal	Small, but the middle layer needs to be developed manually	Very Large
Backend Pattern	Portless WSGI / JS Bridge	Local HTTP Server / JS Bridge	`QWebChannel` / Local HTTP Server
Best For...	Lightweight Windows apps where seamless interaction is key.	Simple, standalone cross-platform apps.	Visually complex, large-scale Qt apps.

⬇️ Installation

⚠️ Note: This library currently supports the Windows platform only.

python -m pip install qtwebview2

Alternatively, you can install from the source:

git clone https://github.com/xiaosuawa/QtWebView2.git
cd QtWebView2
python -m pip install .

Important! The corresponding Qt backend is not installed as a dependency. You need to install your preferred backend (e.g., PySide6 or PyQt6) yourself.

🧑‍💻 Usage

Here is a complete example demonstrating the core features.

import sys
from qtpy.QtWidgets import QApplication, QVBoxLayout, QWidget
from qtpy.QtCore import Slot, QCoreApplication
from qtwebview2 import QtWebView2Widget, DictJsBridge

# Set an application name for the user data folder
QCoreApplication.setApplicationName("QtWebView2-Demo")

# 1. Initialize the application and window
app = QApplication(sys.argv)
window = QWidget()
window.setWindowTitle("QtWebView2-Demo")
window.setGeometry(100, 100, 800, 600)
layout = QVBoxLayout(window)

# 2. Create an instance of the JS bridge
js_bridge = DictJsBridge()

# 3. Create the WebView2 widget and inject the JS bridge
webview = QtWebView2Widget(parent=window, js_apis=js_bridge)
layout.addWidget(webview)


# 4. (JS -> Python) Define a Python function and expose it to JavaScript
@js_bridge.bind_js_api_func
def get_user_os():
    """This Python function will be callable from JavaScript."""
    print(f"Python function 'get_user_os' was called from JavaScript!")
    return sys.platform


# 5. Define HTML content that includes JavaScript to call the Python function
html_content = """
<!DOCTYPE html>
<html>
<head><title>JS Bridge Test</title></head>
<body style="font-family: sans-serif; text-align: center; background-color: #f0f0f0;">
    <h1>QtWebView2 JS Bridge Demo</h1>
    <button onclick="callPython()">Click me to call Python!</button>
    <p>Result from Python: <b id="result">...</b></p>
    <script>
        async function callPython() {
            try {
                // Use async/await to call the Python function and get the result
                const os = await window.qtwebview2.api.get_user_os();
                document.getElementById('result').textContent = os;
            } catch (e) {
                document.getElementById('result').textContent = 'Error: ' + e;
            }
        }
    </script>
</body>
</html>
"""

webview.load_html(html_content)


# 6. (Python -> JS) Connect to a signal and execute JavaScript when it's emitted
@Slot()
def on_dom_loaded():
    """This function is called when the web page's DOM is fully loaded."""
    print(f"DOM content loaded. Executing JS from Python...")
    # You can also execute JavaScript from Python
    webview.evaluate_js("""(function() {
        const new_element = document.createElement('h2');
        new_element.textContent = 'Hello from Python!';
        document.body.appendChild(new_element);
    })()""")


webview.bridge.domContentLoaded.connect(on_dom_loaded)

window.show()
sys.exit(app.exec())

A WSGI Demo(need flask):

import sys
import random
from datetime import datetime

from flask import Flask, jsonify, render_template_string

from qtpy.QtWidgets import QApplication, QVBoxLayout, QHBoxLayout, QWidget, QLabel, QPushButton, QFrame
from qtpy.QtCore import Qt
from qtwebview2 import QtWebView2Widget


flask_app = Flask(__name__)

VIRTUAL_HOST = "myapp.local"

HTML_TEMPLATE = """
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style>
        body { 
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
            padding: 0; margin: 0; 
            background: #f5f7fa; color: #2c3e50; 
            display: flex; justify-content: center; align-items: center; height: 100vh;
        }
        .container { 
            background: white; width: 80%; max-width: 600px;
            padding: 40px; border-radius: 12px; 
            box-shadow: 0 4px 20px rgba(0,0,0,0.08); 
            text-align: center;
        }
        h1 { margin-top: 0; color: #34495e; }
        .tag { 
            background: #e1f5fe; color: #0288d1; 
            padding: 4px 8px; border-radius: 4px; font-size: 0.9em; font-weight: bold;
        }
        button { 
            padding: 12px 24px; background: #00c853; color: white; 
            border: none; border-radius: 6px; cursor: pointer; font-size: 16px;
            transition: background 0.2s;
        }
        button:hover { background: #00e676; }
        #result-box {
            margin-top: 20px; padding: 15px; background: #263238; color: #80cbc4;
            border-radius: 6px; font-family: monospace; text-align: left; min-height: 60px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🐍 Flask + 🖥️ WebView2</h1>
        <p>This is a running in Qt memory <span class="tag">WSGI App</span></p>
        <p>Server Time: <strong>{{ time }}</strong></p>

        <div style="margin: 30px 0;">
            <button onclick="fetchData()">⚡ Initiate a fetch request</button>
        </div>

        <div id="result-box">// Click the button to get the JSON data...</div>
    </div>

    <script>
        async function fetchData() {
            const box = document.getElementById('result-box');
            box.textContent = "// Loading...";
            try {
                const res = await fetch('/api/random', {method: 'POST'});
                const data = await res.json();
                box.textContent = JSON.stringify(data, null, 2);
            } catch(e) {
                box.textContent = "Error: " + e;
            }
        }
    </script>
</body>
</html>
"""


@flask_app.route('/')
def index():
    return render_template_string(HTML_TEMPLATE, time=datetime.now().strftime("%H:%M:%S"))


@flask_app.route('/api/random', methods=['POST'])
def api_random():
    return jsonify({
        "value": random.randint(1000, 9999),
        "source": "Internal Flask Backend",
        "status": "success"
    })


class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QtWebView2 WSGI Demo")
        self.resize(1000, 700)

        main_layout = QVBoxLayout(self)
        main_layout.setContentsMargins(0, 0, 0, 0)
        main_layout.setSpacing(0)

        self.top_bar = QFrame()
        self.top_bar.setFixedHeight(50)
        self.top_bar.setStyleSheet("""
            QFrame { background-color: #ffffff; border-bottom: 1px solid #e0e0e0; }
            QLabel { color: #333; font-size: 14px; font-weight: bold; }
            QPushButton {
                background-color: transparent; border: 1px solid #ccc; border-radius: 4px;
                padding: 5px 15px; color: #555;
            }
            QPushButton:hover { background-color: #f0f0f0; color: #000; }
        """)

        bar_layout = QHBoxLayout(self.top_bar)
        bar_layout.setContentsMargins(15, 0, 15, 0)

        title_label = QLabel("🚀 QtWebView2 Demo")

        self.status_label = QLabel("🟢 WSGI Server Running")
        self.status_label.setStyleSheet("color: #4caf50; font-size: 12px; font-weight: normal;")

        refresh_btn = QPushButton("Reload")
        refresh_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        refresh_btn.clicked.connect(self.reload_webview)

        bar_layout.addWidget(title_label)
        bar_layout.addSpacing(20)
        bar_layout.addWidget(self.status_label)
        bar_layout.addStretch()
        bar_layout.addWidget(refresh_btn)

        self.webview = QtWebView2Widget(
            parent=self,
            wsgi_app=flask_app,
            wsgi_host_name=VIRTUAL_HOST,
            debug=True,
            url=f"http://{VIRTUAL_HOST}/"
        )

        main_layout.addWidget(self.top_bar)

        main_layout.addWidget(self.webview, 1)

    def reload_webview(self):
        self.webview.reload()


if __name__ == "__main__":
    app = QApplication(sys.argv)

    window = MainWindow()
    window.show()
    sys.exit(app.exec())

📦 Packaging

When packaging your application, ensure the files under qtwebview2/lib/ are included — they contain the .NET assemblies and native DLLs required at runtime.

Packager	Notes
PyInstaller	No action needed — a hook is shipped with the package and runs automatically.
Nuitka	Add `--user-package-configuration-file=nuitka-package.config.yml` with the config below, and `--nofollow-import-to=Microsoft,System` to avoid CLR import issues.
Others	Ensure the `lib/` directory remains in its original position under the `qtwebview2` package so the DLLs can be located at runtime. Refer to your packager's documentation for how to include package data.

Nuitka config (nuitka-package.config.yml)

- module-name: 'qtwebview2'
  data-files:
    - dirs:
        - 'lib'
  dlls:
    - from_filenames:
        relative_path: 'lib/runtimes/win-x86/native'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_x86'
    - from_filenames:
        relative_path: 'lib/runtimes/win-x64/native'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_amd64'
    - from_filenames:
        relative_path: 'lib/runtimes/win-arm64/native'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_arm64'
    - from_filenames:
        relative_path: 'lib/x86'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_x86'
    - from_filenames:
        relative_path: 'lib/x64'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_amd64'
    - from_filenames:
        relative_path: 'lib/arm64'
        prefixes:
          - 'WebView2Loader'
      when: 'win32 and arch_arm64'
    - from_filenames:
        relative_path: 'lib'
        prefixes:
          - 'Microsoft.'
      when: 'win32'

License

Distributed under the terms of the Mozilla Public License Version 2.0.

Project details

These details have been verified by PyPI

Project links

Homepage

GitHub Statistics

Maintainers

xiaosu

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.6.0rc9 pre-release

Jun 16, 2026

0.6.0rc8 pre-release

Jun 16, 2026

0.6.0rc7 pre-release

Jun 16, 2026

0.6.0rc6 pre-release

Jun 12, 2026

0.6.0rc5 pre-release

Jun 12, 2026

0.6.0rc4 pre-release

Jun 11, 2026

0.6.0rc3 pre-release

Jun 10, 2026

0.6.0rc2 pre-release

Jun 8, 2026

0.6.0rc1 pre-release

Jun 7, 2026

This version

0.5.0

Jun 6, 2026

0.4.2

May 27, 2026

0.4.1

Feb 26, 2026

0.4.0

Feb 26, 2026

0.3.0

Jan 23, 2026

0.2.0

Dec 1, 2025

0.1.1

Oct 24, 2025

0.1.0

Oct 24, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qtwebview2-0.5.0.tar.gz (392.1 kB view details)

Uploaded Jun 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

qtwebview2-0.5.0-py3-none-any.whl (388.9 kB view details)

Uploaded Jun 6, 2026 Python 3

File details

Details for the file qtwebview2-0.5.0.tar.gz.

File metadata

Download URL: qtwebview2-0.5.0.tar.gz
Upload date: Jun 6, 2026
Size: 392.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for qtwebview2-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`62e1dbeb91ea1a8329be9eefd4d35413fb59402fbd038fad0b8ac5e4a1145d63`
MD5	`04b46b64c9a2f8be02bb58c6736c3a11`
BLAKE2b-256	`938f875b030c2c8d3bcd601b6e344e0cb2cf0bd20d631ee8beef8b4d1b60cd2f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for qtwebview2-0.5.0.tar.gz:

Publisher: publish-to-pypi.yml on xiaosuawa/QtWebView2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: qtwebview2-0.5.0.tar.gz
- Subject digest: 62e1dbeb91ea1a8329be9eefd4d35413fb59402fbd038fad0b8ac5e4a1145d63
- Sigstore transparency entry: 1740979217
- Sigstore integration time: Jun 6, 2026
Source repository:
- Permalink: xiaosuawa/QtWebView2@fdca767552f6f4516914e2fa1cab1e4a23ae2dbc
- Branch / Tag: refs/tags/v0.5.0
- Owner: https://github.com/xiaosuawa
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-to-pypi.yml@fdca767552f6f4516914e2fa1cab1e4a23ae2dbc
- Trigger Event: release

File details

Details for the file qtwebview2-0.5.0-py3-none-any.whl.

File metadata

Download URL: qtwebview2-0.5.0-py3-none-any.whl
Upload date: Jun 6, 2026
Size: 388.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for qtwebview2-0.5.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ba62c0e018dc95c9463cd7c6d2d009e2c6a29589deeb6baf32c4bde205b250a3`
MD5	`e6d16906a327fa430de7bb5b0db6a423`
BLAKE2b-256	`4ac41a4beea709c29231c96910f68bf05fc5c8077902709ea6e929259c582354`

See more details on using hashes here.

Provenance

The following attestation bundles were made for qtwebview2-0.5.0-py3-none-any.whl:

Publisher: publish-to-pypi.yml on xiaosuawa/QtWebView2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: qtwebview2-0.5.0-py3-none-any.whl
- Subject digest: ba62c0e018dc95c9463cd7c6d2d009e2c6a29589deeb6baf32c4bde205b250a3
- Sigstore transparency entry: 1740979222
- Sigstore integration time: Jun 6, 2026
Source repository:
- Permalink: xiaosuawa/QtWebView2@fdca767552f6f4516914e2fa1cab1e4a23ae2dbc
- Branch / Tag: refs/tags/v0.5.0
- Owner: https://github.com/xiaosuawa
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-to-pypi.yml@fdca767552f6f4516914e2fa1cab1e4a23ae2dbc
- Trigger Event: release

qtwebview2 0.5.0

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

QtWebView2

📖 Introduction

✨ Features

🤔 Quick Comparison

⬇️ Installation

🧑‍💻 Usage

📦 Packaging

License

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance