PyGWalker Spec Files

A PyGWalker spec stores chart state. Use spec_path for local files that PyGWalker should load from or save to, and use spec for inline JSON, config IDs, or remote specs.

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

`spec_path` vs `spec`

Option	Use for	Example
`spec_path`	Local chart-state files	`spec_path="./gw_config.json"`
`spec`	Inline JSON, config ID, or remote spec URL	`spec='[{"name":"Chart 1", ...}]'`

For new local-file examples, prefer spec_path. It makes file persistence explicit and avoids ambiguity with inline JSON or remote specs.

Save and reuse chart state

Use read-write spec mode when the adapter exposes saving.

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

Streamlit and Gradio also support spec_io_mode:

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

Render saved charts

Use render when you want saved charts without the full explorer.

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

Use to_render_html for a static renderer export.

from pygwalker.api.html import to_render_html
 
html = to_render_html(df, spec_path="./gw_config.json", computation="browser")

Migrate older specs

pygwalker.spec.migrate updates a saved PyGWalker or Graphic Walker spec to the current schema shape.

import json
import pygwalker as pyg
 
migrated = pyg.spec.migrate("./old_gw_config.json")
 
with open("./gw_config.json", "w", encoding="utf-8") as f:
    json.dump(migrated, f, ensure_ascii=False, indent=2)

Signature:

pygwalker.spec.migrate(spec, *, version=None) -> dict

spec can be:

Input	Accepted
Loaded Python object	`dict` or `list`
JSON string	Yes
Existing local file path	Yes

If a string looks like invalid JSON or the file path does not exist, migrate raises ValueError.

Common traps

Trap	Fix
Passing a local file through `spec` in new code	Use `spec_path`.
Expecting static HTML to save edits back to `spec_path`	Use a live notebook/app backend with save support.
Passing `spec_path` to an adapter that already received a `Walker`	Put the spec path on the original `Walker`.
Migrating a remote spec URL with `spec.migrate`	Load the spec object first, then pass the object or JSON string.

Related Guides

Component API Appearance