English · 简体中文

desktop_flask

Run a Flask app in a desktop window: WebView2 renders the UI, an in-process WSGI bridge serves it, and no TCP port is ever opened.

desktop_flask is a standalone extension library — it does not modify Flask's source. You keep from flask import Flask and add one line:

from flask import Flask
import desktop_flask

app = Flask(__name__)
desktop_flask.init_app(app)          # ← the only wiring step

@app.get("/")
def get_index():
    return render_template("index.html")

if __name__ == "__main__":
    app.run_desktop(title="My tool")

Or without any injection:

desktop_flask.run_desktop(app, title="My tool")

From the command line:

flask --app myapp desktop                      # via the flask.commands entry point
flask --app myapp desktop --self-check         # built-in WebView2 self check (S1–S19)

desktop-flask myapp:app --title "My tool"      # launcher, no Flask CLI needed
python -m desktop_flask myapp:create_app()     # the same thing

Status: 0.1.0.dev1 — developer preview. The bridge core, the Flask integration, the WebView2 host and the packaging story are done and tested on a real machine, but the API and the DESKTOP_* keys may still shift before 0.1.0. Desktop-specific optimisations are still ahead. Breaking changes will be listed in CHANGELOG.md.

Install

pip install desktop_flask

That is enough on Windows: pythonnet is a base dependency (sys_platform == 'win32'), so run_desktop() works right after installing. desktop_flask[desktop] is still accepted as an alias for older instructions.

• The WebView2 Runtime is required at run time. Windows 11 has it; older Windows 10 may not. run_desktop(install_runtime=True) can offer to install it.
• The WebView2 managed DLLs and native loader are bundled in the package, so there is no separate download step.
• Windows only for now. There is no macOS/Linux backend — run_desktop() says so instead of silently opening a port.

⚠️ Do not put a version range in your requirements for this pre-release: desktop_flask>=0.1 does not resolve, because pip excludes pre-releases when the requirement carries a specifier. Plain pip install desktop_flask and pip install desktop_flask==0.1.0.dev1 both work. Once 0.1.0 is published, ranges start working and upgrades move to the final release automatically.

What it changes

Packaging your own app into an exe

pip install "desktop_flask[desktop,build]"
desktop-flask-build app.py

You get build/app.dist/ — ship that whole directory. Nuitka also needs a C compiler (MSVC or MinGW64); pip cannot install it, and the tool's preflight will tell you if it is missing before starting a ten-minute compile. See docs/packaging.md for the two traps that make a build succeed and still not run, and for the distribution checklist.

Reading the docs offline

The documentation ships inside the package, so it is readable without any network access:

desktop-flask-docs                  # list the pages (Chinese, the fuller set)
desktop-flask-docs --en             # English pages
desktop-flask-docs packaging --cat  # print one page

What's inside

Documentation

Developer-facing design notes (architecture, measured findings, ADRs) live in the carrier repository this library was developed in: DESKTOP_MODE_DESIGN.md and the m0_spike/, m1_bridge/, m3_host/, m4_engineering/ conclusion documents. They are not part of this package.

Boundaries (by design, not bugs)

• No WebSocket. The constructor itself refuses a non-http(s)/ws(s) URL on a custom scheme. Use desktop_flask.emit() / desktopFlask.invoke().
• No SSE / streaming responses. WebView2 requires the complete body before the deferral completes. Push progress through the message bridge instead.
• Cookies are the bridge's, not Chromium's. document.cookie stays empty — that is expected. localStorage / IndexedDB work normally.
• No Service Worker (Blink requires http/https).
• Windows only for now; the interface is designed to be extended.

Not part of Flask

desktop_flask is an independent extension library: it is not part of Flask and is not affiliated with, or endorsed by, the Pallets organisation. It redistributes Microsoft's WebView2 assemblies verbatim under their own license. See LICENSE.txt (BSD-3-Clause) and NOTICE.md for the full attribution list.

Layout

This directory is the library's repository root — src/, tests/, scripts/, docs/ and examples/ are siblings here, so the whole directory can be pushed as a standalone repository.

src/desktop_flask/          the library
├── bridge.py               WSGI bridge: environ, WSGI call, response capture
├── adapter.py              makes url_for(_external=True) produce df:// URLs
├── cookies.py              bridge-managed cookie jar
├── bodystore.py            memory vs. temp file for request/response bodies
├── cache.py                static asset LRU + HTTP conditional requests
├── pipeline.py             cache + bridge, host-independent
├── workers.py              request thread pool + deferral lifetime
├── runtime.py              single instance, crash reports, Runtime detection/install
├── _frozen.py              "is this a frozen build?" (Nuitka does not set sys.frozen)
├── origin.py               origin strategies (df://app, http://df.localhost)
├── compat.py               legacy-origin forwarding, body rewriting, navigation policy
├── messages.py             postMessage message bus (the WebSocket replacement)
├── selfcheck.py            built-in S1–S19 self check page
├── server.py               DebugHttpServer (development only; opens a port)
├── integration.py          init_app(): runtime wiring, no Flask patch
├── packaging.py            desktop-flask-build (Nuitka)
├── docs.py                 desktop-flask-docs (the bundled documentation)
├── cli.py                  `flask desktop`
├── run.py / __main__.py    `desktop-flask` launcher
├── assets/                 icon (generated by scripts/make_icon.py)
├── _vendor/webview2/       WebView2 managed DLLs + native loader (vendored)
└── platforms/windows.py    WebView2 host (pythonnet + WinForms)
docs/                       documentation (English)
docs/zh/                    documentation (Simplified Chinese)
scripts/                    fetch_webview2_dlls.py, make_icon.py, build_nuitka.py, frozen_probe.py
tests/                      the library's test suite
examples/desktop_demo/      a demo app showing cache / workers / message bridge
examples/tutorial/          the official Flask tutorial, run unchanged (acceptance)
pyproject.toml              distribution metadata
LICENSE.txt / NOTICE.md     license and third-party attribution
CHANGELOG.md                what changed, and the version policy