PyGWalker Streamlit API

Use StreamlitRenderer to embed PyGWalker in a Streamlit app. Cache the renderer when the dataset and chart state are reused across reruns.

import pandas as pd
import streamlit as st
from pygwalker.api.streamlit import StreamlitRenderer
 
st.set_page_config(page_title="PyGWalker", layout="wide")
 
@st.cache_resource
def get_renderer():
    df = pd.read_csv("data.csv")
    return StreamlitRenderer(
        df,
        spec_path="./gw_config.json",
        spec_io_mode="rw",
        computation="kernel",
    )
 
renderer = get_renderer()
renderer.explorer()

Constructor

StreamlitRenderer(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="r",
    computation=None,
    kernel_computation=None,
    use_kernel_calc=None,
    show_cloud_tool=None,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

dataset can be a pandas DataFrame, polars DataFrame, pyarrow Table, database Connector, or reusable pygwalker.Walker.

Key options

Option	Default	Notes
`spec_path`	`None`	Local chart-state file. Prefer this for local files.
`spec_io_mode`	`"r"`	Use `"rw"` when the Streamlit UI should save chart edits back to the spec file.
`computation`	`None`	Use `"browser"`, `"kernel"`, or `"cloud"` to force a mode. Automatic Streamlit behavior defaults to kernel-side computation.
`show_cloud_tool`	`None`	Controls cloud UI visibility when available.
`default_tab`	`"vis"`	Initial explorer tab.

kernel_computation and use_kernel_calc are legacy compatibility options. Prefer computation; the legacy flags are scheduled for removal in PyGWalker 0.7.0.

Main methods

Method	Use
`renderer.explorer(key="explorer", default_tab="vis")`	Full drag-and-drop explorer.
`renderer.viewer(key="viewer")`	View-only/filter-renderer UI.
`renderer.chart(index, key="chart", size=None, pre_filters=None)`	Render a saved chart by zero-based index.
`renderer.table(key="table")`	Render the table view.
`renderer.set_global_pre_filters(pre_filters)`	Apply filters across charts unless a chart call overrides them.

Render a saved chart

After saving charts to spec_path, render one chart by index.

renderer.chart(0, size=(720, 420))

Use PreFilter to apply chart-level filters.

from pygwalker.api.streamlit import PreFilter
 
renderer.chart(
    0,
    pre_filters=[
        PreFilter(field="category", op="one of", value=["A", "B"]),
        PreFilter(field="revenue", op="range", value=[0, 100000]),
    ],
)

PreFilter accepts:

PreFilter(
    field: str,
    op: "range" | "temporal range" | "one of",
    value: list[int | float | str],
)

For op="temporal range", values can be millisecond timestamps or parseable date strings.

Reuse a `Walker`

If the same dataset and options should be shared with other adapters, construct a Walker first.

import pygwalker as pyg
from pygwalker.api.streamlit import StreamlitRenderer
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
renderer = StreamlitRenderer(walker)
renderer.explorer()

When passing a Walker, put construction options on pyg.Walker(...). StreamlitRenderer(walker, spec_path="./other.json") is rejected because it would conflict with the existing object.

`get_streamlit_html`

get_streamlit_html returns the HTML string used by the Streamlit component.

from pygwalker.api.streamlit import get_streamlit_html
 
html = get_streamlit_html(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    mode="explore",
    computation="kernel",
)

Supported modes are "explore", "filter_renderer", and "table".

Common traps

Trap	Fix
Recreating `StreamlitRenderer` on every rerun	Wrap construction in `@st.cache_resource`.
Using `spec="./gw_config.json"` for local files	Use `spec_path="./gw_config.json"`.
Passing construction options after providing a `Walker`	Move those options to `pyg.Walker(...)`.
Starting new code with `kernel_computation=True`	Use `computation="kernel"`.