PyGWalker API Reference

Use pygwalker.walk(df) for a quick interactive explorer. Use pygwalker.Walker(...) when the same dataset, chart state, and computation mode should be reused across notebooks, Streamlit, webserver, or HTML export.

import pygwalker as pyg
 
walker = pyg.Walker(df, spec_path="./gw_config.json", computation="browser")
walker.show()

Choose an entrypoint

API	Best for	Notes
`pygwalker.walk(dataset, ...)`	Quick exploration in notebooks or scripts	Uses anywidget in Jupyter by default and a local webserver outside notebooks.
`pygwalker.Walker(dataset, ...)`	Reusing one PyGWalker object across adapters	Put construction options such as `spec_path`, `field_specs`, and `computation` on the `Walker`.
`pygwalker.render(dataset, spec=..., ...)`	Rendering saved charts without the full explorer	Use `spec_path` for local chart files.
`pygwalker.table(dataset, ...)`	Opening the table/profiling view	Accepts the same dataset and computation options as `render`.
`pygwalker.to_html(dataset_or_walker, ...)`	Static HTML export	Browser-only. It rejects `computation="kernel"` and `computation="cloud"`.
`StreamlitRenderer(dataset_or_walker, ...)`	Streamlit apps	Cache the renderer with `st.cache_resource` for long-lived apps.
`get_html_on_gradio(dataset, ...)`	Gradio apps	Return the iframe HTML and mount `PYGWALKER_ROUTE`.
`pygwalker.component(dataset, ...)`	Programmatic chart builders	Chain mark, encode, layout, and export methods.
`pygwalker.spec.migrate(spec)`	Updating saved chart state	Accepts a loaded spec object, JSON string, or local file path.

Supported datasets

Most public APIs accept pandas DataFrame, polars DataFrame, pyarrow Table, database Connector, and connector-style SQL/data-source strings where the adapter supports connectors. pygwalker.walk, notebook anywidget/marimo/webserver adapters, StreamlitRenderer, and to_html can also accept a reusable pygwalker.Walker object.

See Dataset Inputs for details and examples.

Common options

Option	Type	Default	Use
`spec_path`	`str` or `None`	`None`	Local chart-state file to load from and save to. Prefer this over passing a local file path through `spec`.
`spec`	`str`	`""`	Inline JSON, config ID, or remote spec URL.
`computation`	`auto`, `browser`, `kernel`, `cloud`, or `None`	`None`	Choose where PyGWalker runs data queries. Omit it or use `"auto"` for automatic behavior.
`field_specs`	`List[FieldSpec]` or `None`	`None`	Override inferred field semantic and analytic types.
`theme_key`	`vega`, `g2`, or `streamlit`	`"g2"`	Select the renderer theme family.
`appearance`	`media`, `light`, or `dark`	`"media"`	`media` follows the operating system color scheme.
`default_tab`	`data` or `vis`	`"vis"`	Choose the initial tab for explorer views.

Computation modes

Use computation, not the legacy computation booleans.

Value	Behavior	Typical use
omitted or `"auto"`	Keep PyGWalker's automatic mode selection	Default for most users.
`"browser"`	Run data queries in the frontend/browser	Static HTML exports and smaller local data.
`"kernel"`	Run queries through local DuckDB-backed Python computation	Larger local datasets in live notebook, Streamlit, Gradio, or webserver sessions.
`"cloud"`	Run queries through Kanaries cloud computation	Cloud-backed workflows with a Kanaries API key.

kernel_computation, cloud_computation, and use_kernel_calc are legacy compatibility flags. They are deprecated and scheduled for removal in PyGWalker 0.7.0. Do not combine enabled legacy flags with a non-auto computation value; PyGWalker raises ValueError.

See Computation Modes for migration examples.

Reuse a `Walker`

Create a Walker when multiple adapters should share one configuration.

import pygwalker as pyg
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
walker.show()
renderer = walker.to_streamlit()

When an adapter receives a Walker, construction options must already be on the Walker. For example, pyg.to_html(walker, spec_path="./other.json") is rejected because it would try to rebuild the existing object with conflicting state.

Static HTML limits

Static HTML exports do not have a live Python or cloud backend. Use computation="browser" or omit the computation option when calling pyg.to_html(...), walker.to_html(), or component HTML exports. Use a live adapter such as Notebook APIs, Streamlit, or Gradio for kernel or cloud computation.