h2o-wave

library1.8.9pypypi✓ verified 84d ago

H2O Wave is a lightweight software stack for building beautiful, low-latency, real-time, browser-based applications and dashboards entirely in Python, without requiring HTML, Javascript, or CSS expertise. It excels at capturing data, visualizations, and graphics from multiple sources and broadcasting them live over the web. The current version is 1.8.4, with frequent releases often including security updates.

web-framework data http-networking communication

pip install h2o-wave

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · H2O-WAVE

h2o-wave

web-frameworkpythonv1.8.9

Install

3.9s avg

Import

621ms

Disk

31MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.9 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.656s · 34.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.9s · import 0.586s · 35MB

31MB installed

● package 31MB

Code

Verified usage

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

✓ from h2o_wave import Q

The 'query' object (q) passed to app handlers, containing request arguments and methods for page manipulation.

main

✓ from h2o_wave import main

Used to mark the entry point function for a Wave app.

app

✓ from h2o_wave import app

Decorator to register a Python function as a Wave app at a specific route.

✓ from h2o_wave import ui

Module containing all UI components (cards, widgets) for building the application interface.

This 'Hello World' example demonstrates a basic Wave application. It defines a single page with a Markdown card displaying a title and content. The `@app('/')` decorator registers the `serve` function to handle requests at the root URL. The `Q` object provides access to the current page and other context. `ui` is used to create UI components. Finally, `await q.page.save()` sends the page updates to the browser.

from h2o_wave import Q, app, ui, main @app('/') async def serve(q: Q): q.page['hello'] = ui.markdown_card( box='1 1 2 2', title='Hello World!', content='This is a simple H2O Wave app.' ) await q.page.save() # To run this app, save it as `app.py` and execute `wave run app.py` in your terminal. # Then, navigate to http://localhost:10101 in your browser.

wave --version

Debug

Known issues

breakingWave 1.0 introduced minor breaking changes, particularly affecting routing. The `handle_on` mechanism was introduced to address issues with `q.args` order, which could lead to unexpected behavior in older versions.

fix

Review the official Wave 1.0 changelog and update routing logic, preferably adopting the `handle_on` mechanism for reliable event handling.

affects: <1.0

gotchaWhen deploying with an ASGI server like Uvicorn, the Wave server (`waved`) must be run separately from the Python app. `wave run` automatically starts `waved` for development, but for production, you need to manage both processes independently.

fix

Ensure `waved` (the Go-based Wave server) is running and accessible to your Python Wave app, usually via `H2O_WAVE_ADDRESS` environment variable if on separate machines or containers.

affects: All versions

gotchaIncorrect usage of state scopes (`q.app`, `q.user`, `q.client`) can lead to performance or UX issues. For example, loading a static dataset into `q.client` will cause it to be re-uploaded for every browser connection, wasting resources.

fix

Understand and correctly apply state scopes: `q.app` for global application state, `q.user` for per-user state across all their sessions, and `q.client` for per-browser-tab state.

affects: All versions

gotchaIn `unicast` mode (the default for applications), if a button click or other event handler does not result in *any* UI update (e.g., just printing to console), the UI may appear to hang with an infinite loading spinner.

fix

Always ensure your app handler explicitly updates at least one UI element, even a non-existent one (`q.page['non-existent'].items = []`), or provide user feedback, to clear the loading spinner.

affects: All versions

gotchaDisabling TLS verification using `H2O_WAVE_NO_TLS_VERIFY` environment variable or `--no-tls-verify` parameter is a significant security risk and should only be done for development purposes, never in production environments.

fix

For production, ensure proper TLS certificates are configured and verified for all communication, and do not disable TLS verification.

affects: All versions

Errors

Common errors & fixes

httpx connection err [Errno 111] Connect call failed

The Python Wave app (running via Uvicorn, Gunicorn, etc.) cannot connect to the H2O Wave server (`waved`). This often happens when `waved` is not running or is not accessible at the expected address/port.

fix

Start the `waved` server separately. If running on different hosts or non-default ports, configure the Wave app with `H2O_WAVE_ADDRESS` environment variable to point to the correct `waved` address, e.g., `H2O_WAVE_ADDRESS='http://your-waved-host:10101'`.

UI hangs in an infinite loading spinner after button click (in unicast mode).

The app handler for the button click event completed without making any changes to `q.page` or updating any UI component. In unicast mode, the browser expects a UI update to acknowledge the event and dismiss the loading state.

fix

Even if no visual change is intended, explicitly update a UI component or a dummy card within your handler (e.g., `q.page['feedback_card'] = ui.message_bar(type='info', text='Action complete!')` or `q.page['temp'].items = []`) before `await q.page.save()`.

urllib.error.URLError: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (on macOS during `wave fetch`)

This error on macOS indicates that Python's SSL certificate store is not correctly configured or updated, preventing it from verifying SSL certificates when downloading resources.

fix

Navigate to `/Applications/Python X.Y` (where X.Y is your Python version) and execute the `Install Certificates.command` script. This updates the certificate store.

Upgrade

Version history

1.8.9latest on PyPI · released Jun 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/h2oai/wave ↗

packagehttps://pypi.org/project/h2o-wave/ ↗

homepagehttps://wave.h2o.ai/ ↗

docshttps://wave.h2o.ai/ ↗

changeloghttps://github.com/h2oai/wave/releases ↗