# Pywebview Desktop Apps
> Use for Python desktop GUI apps shipped as a single .exe.
- Skill: `wcpaka-lgtm/pywebview-desktop-apps` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add wcpaka-lgtm/pywebview-desktop-apps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wcpaka-lgtm/pywebview-desktop-apps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wcpaka-lgtm (https://skillmd.com/u/wcpaka-lgtm)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/wcpaka-lgtm/pywebview-desktop-apps
---
# pywebview Desktop Apps
Build native-feeling desktop apps with a Python backend and a web-technology frontend, packaged as a single executable. Stack: **pywebview** (native window + JS↔Python bridge) + domain libs (ebooklib/pandas/pillow/…) + **PyInstaller** (single-file packaging).
## When to use
Trigger phrases:
- "데스크톱 앱 만들어줘", "exe 파일로", "세련된 앱", "GUI 프로그램"
- "make me a desktop app / a little tool with a UI / package this as an exe"
- User wants a polished standalone utility (reader, viewer, editor, dashboard, converter)
NOT for:
- One-off HTML mockups → `claude-design`, `sketch`, `popular-web-designs`
- Browser games → `browser-game-development`
- Cross-platform with native widgets (Qt-style) → recommend PySide6 instead
## Architecture
```
┌─────────────────────────────────────────┐
│ Native window (pywebview / WebView2) │
│ ┌───────────────────────────────────┐ │
│ │ HTML/CSS/JS UI (single string │ │
│ │ or bundled file) │ │
│ │ │ │
│ │ window.pywebview.api.method() │──┼──► Python Api class
│ └───────────────────────────────────┘ │ (your domain logic)
└─────────────────────────────────────────┘
```
**Why pywebview over Electron**: ~30MB exe vs ~150MB, uses the OS's webview (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux), pure Python backend, no Node toolchain.
**Why over Tkinter/Qt**: modern CSS styling, flexbox/grid layouts, animations, the entire web design ecosystem.
## Workflow
### 1. Scaffold the app (single file is fine to start)
```python
import webview, json
class Api:
def do_thing(self, arg):
# Python domain logic — return JSON strings to JS
return json.dumps({"result": ...}, ensure_ascii=False)
HTML_UI = r"""
...your UI...
"""
if __name__ == '__main__':
api = Api()
window = webview.create_window(
'My App', html=HTML_UI, js_api=api,
width=1100, height=750, min_size=(800, 600),
background_color='#1a1a2e', text_select=True,
)
webview.start(debug=False) # debug=True opens DevTools
```
See `templates/app_skeleton.py` for a fuller starter (file dialog, theming, settings persistence).
### 2. Install deps
```bash
pip install pywebview pyinstaller
pip install # ebooklib, pandas, pillow, etc.
pip install # beautifulsoup4, lxml — see pitfall #1
```
### 3. Smoke-test BEFORE packaging
Run `python app.py` in a background terminal and verify the window renders:
```
terminal(background=true): cd ~/myapp && python app.py
computer_use(action='capture', app='python', mode='vision') # confirm UI rendered
process(action='kill')
```
This catches missing modules and broken JS↔Python calls before you waste a 60-second PyInstaller build.
### 4. Package with PyInstaller
```bash
pyinstaller --noconfirm --onefile --windowed \
--name "MyApp" \
--hidden-import= --hidden-import= \
--collect-all \
app.py
```
Flag cheat sheet:
- `--windowed` — no console window (REQUIRED for GUI apps; omit for debugging to see tracebacks)
- `--onefile` — single exe (slower startup, ~5s extract; use `--onedir` if startup time matters)
- `--collect-all ` — bundle a package's data files + submodules (needed for libs like `ebooklib`, `babel`, anything with templates/locales)
- `--hidden-import=` — force-include modules PyInstaller's static analysis misses (libs that import dynamically)
- `--icon=app.ico` — custom icon (Windows wants .ico, not .png)
Output: `dist/MyApp.exe` (or `dist/MyApp.app` on macOS).
### 5. Verify the exe
```
terminal(background=true): ./dist/MyApp.exe
computer_use(action='capture', app='MyApp', mode='vision')
```
Confirm the window title, UI rendered, no crash dialog. Then `process(action='kill')`.
## Pitfalls
1. **Transitive deps not auto-detected.** A lib like `ebooklib` imports `bs4` lazily — `pip install ebooklib` does NOT install bs4, and the app crashes with `ModuleNotFoundError` on first use. Fix: run the app once, read the traceback, `pip install` the missing module, repeat. Common offenders: `beautifulsoup4`, `lxml`, `html5lib`, `Pillow` (for image libs).
2. **PyInstaller misses dynamic imports.** If a module is imported via `importlib` or string-based lookup, PyInstaller won't see it. Symptom: exe runs but feature X silently fails. Fix: `--hidden-import=`. For whole packages with data files, `--collect-all ` is the bigger hammer.
3. **`--windowed` hides tracebacks.** If the exe crashes on startup you see nothing. Debug build: drop `--windowed` temporarily, run the exe from a terminal, read the console. Or `webview.start(debug=True)` for in-app DevTools.
4. **File paths break under `--onefile`.** PyInstaller extracts to a temp dir at runtime; `__file__`-relative paths point into the bundle. Use this helper for any bundled asset:
```python
def resource_path(rel):
base = getattr(sys, '_MEIPASS', os.path.abspath('.'))
return os.path.join(base, rel)
```
User-facing paths (open/save dialogs, config files) should use `Path.home()` or app-data dirs, NOT the bundle dir.
5. **`create_file_dialog` API drift.** Older pywebview: `window.create_file_dialog(webview.OPEN_DIALOG, ...)`. Newer (6.x): deprecation warning, prefers `FileDialog.OPEN`. Both still work as of 6.2; if you see the deprecation warning, the old form is fine for now but plan to migrate.
6. **JS↔Python returns strings only.** `js_api` methods must return JSON-serializable values; complex objects need `json.dumps(..., ensure_ascii=False)` (Korean/CJK will mojibake without `ensure_ascii=False`). On the JS side, `JSON.parse(await window.pywebview.api.method())`.
7. **Don't use shell `&` backgrounding in `terminal()`.** Hermes rejects `cmd &`. Use `terminal(background=true)` and `process(action='poll'/'kill')`.
8. **Content links navigate the webview → black screen (CRITICAL for content viewers).** If your app renders *external* HTML (EPUB chapters, markdown, saved pages) into the webview, any `` the user clicks makes the webview try to **navigate** to a URL that doesn't exist → blank/black screen, app appears frozen and untouchable. This was a real user-reported bug. Fix: after injecting content, attach a click handler to every `` that calls `e.preventDefault(); e.stopPropagation()`, then resolve the href yourself (exact match → normalized relative path → basename fallback) and route to the right content via your Python API. Same-chapter `#anchors` should smooth-scroll; `http(s)://` links should open in the real browser (`webbrowser.open` via an API method). **Never let the webview itself navigate.**
9. **Tap-zone UIs must not fire on scroll-drags.** For e-reader-style zones (left 30% = prev / center = menu toggle / right 30% = next), use `pointerdown` + `pointerup` and treat it as a click ONLY if: pointer moved < ~10px, elapsed < ~600ms, `window.getSelection().isCollapsed` (no text selection), and the target isn't `a/button/input/select`. Also ignore clicks within ~20px of the right edge (scrollbar). Otherwise a normal scroll gesture turns a page. Show a subtle `‹`/`›` hover indicator so zones are discoverable.
10. **pywebview has NO native file-drop event.** To support drag-and-drop file opening, use JS `dragenter/dragover/dragleave/drop` listeners on `document`, read the dropped file via `file.arrayBuffer()`, base64-encode in 8KB chunks (`String.fromCharCode.apply(null, subarray)`), send to a Python API method that writes to a `tempfile.NamedTemporaryFile(delete=False)`, loads it, then `os.unlink`s the temp. Show a full-screen overlay (`position:fixed; inset:0; z-index:9999; pointer-events:none`) with a dashed border box during drag. Use a `dragCounter` (increment on dragenter, decrement on dragleave) to handle nested element enter/leave correctly. Validate extension before processing.
11. **PyInstaller rebuild fails if the exe is still running.** Windows locks the file → `PermissionError: [WinError 5]` on `os.remove`. Fix: `taskkill //F //IM MyApp.exe` first (note: in MSYS/git-bash, use `//F` not `/F` to avoid path mangling), then rebuild. If taskkill doesn't release the lock immediately, `mv dist/MyApp.exe dist/MyApp_old.exe` works as a fallback since rename doesn't need the same lock as delete.
12. **ebooklib `Section` is a subclass of `Link`.** When flattening `book.toc`, check `isinstance(item, epub.Section)` BEFORE `isinstance(item, epub.Link)` in the elif chain — otherwise Sections are silently treated as Links and lose their heading semantics. Sections without an href should resolve to their first child chapter's index for a better UX (clicking a volume heading jumps to its first chapter).
13. **Python-side and JS-side DOM selectors MUST match exactly for index-based features.** When Python extracts elements (e.g. `BeautifulSoup.find_all(['p','h1',...])`) and JS tags/highlights the same elements (e.g. `querySelectorAll('p, h1, ...')`), the selector lists must be identical — same tags, same order, same filtering rules (e.g. `len >= 2`). If Python includes `div` but JS doesn't (or vice versa), highlight indices will be misaligned and the wrong paragraph gets highlighted. This is a silent bug — no error, just wrong UX. Test by counting elements on both sides for a known document.
14. **TTS: prefer paragraph-level over sentence-level.** Users find sentence-by-sentence playback choppy. Extract block elements (`p`, `h1`–`h6`, `li`, `blockquote`) as units and pass each whole paragraph to `synthesize()` — modern TTS engines (Supertonic-3) handle internal chunking with natural pauses. This also makes highlight tracking simpler (one highlight per paragraph, not per sentence).
15. **HTML defined AFTER the `