H2O Wave

1.8.4 · active · verified Thu Apr 16

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.

Common errors

```
httpx connection err [Errno 111] Connect call failed
```
cause 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).
```
cause 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`)
```
cause 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.

Warnings

breaking Wave 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.
gotcha When 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.
gotcha Incorrect 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.
gotcha In `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.
gotcha Disabling 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.

Install

pip install h2o-wave Install with pip

Imports

Q
```
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.
ui
```
from h2o_wave import ui
```
Module containing all UI components (cards, widgets) for building the application interface.

Quickstart

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.

view raw JSON →