PyGWalker

For developers looking to extend their knowledge or seek help, the following resources are available:

• Research: Read the PyGWalker Paper for the theoretical foundation of on-the-fly exploratory visual data analysis.
• Core Engine: Learn more about Graphic Walker, the underlying engine.
• Advanced Automation: Explore RATH, an open-source automated exploratory data analysis software.
• Integrations: See the guide for using pygwalker with Streamlit to build visual analytics apps.
• Support: Join the community on Slack or Discord for troubleshooting and assistance.

pygwalker is compatible with a wide range of notebook and web application environments. Key supported platforms include:

• Notebooks: Jupyter Notebook, Jupyter Lab, Jupyter Lite, Google Colab, Kaggle Code, and Databricks Notebook (v0.1.4a0+).
• IDE Extensions: Jupyter extension for Visual Studio Code (v0.1.4a0+).
• Web Apps: Streamlit (v0.1.4.9+) via pyg.walk(df, env='Streamlit'), DataCamp Workspace (v0.1.4a0+), and marimo (v0.4.9.11).
• Other: Panel (via panel-graphic-walker) and most web applications compatible with IPython kernels (v0.1.4a0+).

PyGWalker is a hybrid library consisting of a Python package and a React frontend.

• Python package (pygwalker/): Provides the public API (walk, render, table), handles dataframe parsing, and manages the communication transports that exchange data and chart specifications with the UI.
• Frontend app (app/): A React + Vite application. During the build process, it is compiled into JavaScript bundles and stored in pygwalker/templates/dist/ within the Python wheel.

At runtime, the Python side serializes the dataframe and configuration, then hands the JavaScript bundles to the notebook or browser. The UI then communicates back to the Python kernel to fetch data, execute queries, and save chart specifications.

Communication between the kernel and the frontend follows a standardized envelope defined in protocol.py (Python) and comm.generated.ts (TypeScript).

Request Envelope:

• action: The operation to perform (e.g., get_datas, save_chart, update_spec, export).
• data: The payload for the action.
• rid: Request ID.
• gid: Widget/App ID.

Response Envelope:

• code: Status/error code.
• data: The requested data payload.
• message: Status message.

When using pyg.walk(), you can use specific parameters to manage chart configurations and large datasets:

• spec: A JSON string or file path used to save or load chart configurations (e.g., settings saved manually in the UI).
• kernel_computation: A boolean flag. When set to True, it uses DuckDB as the computation engine, which is recommended for working with large datasets (up to 100 GB) locally.

Note: use_kernel_calc is deprecated; use kernel_computation instead.

df = pd.read_csv('./bike_sharing_dc.csv')
walker = pyg.walk(
    df,
    spec="./chart_meta_0.json",    # configuration saved manually in UI
    kernel_computation=True,       # enable DuckDB for large datasets
)

When building a Reflex application that integrates PyGWalker, follow the standard Reflex package structure to ensure the app is correctly imported as app.app.

Required structure:

• rxconfig.py: Must contain app_name="app".
• app/: A directory containing the Python package.
• app/app.py: Must contain the app = rx.App() object.

Example structure:

project_root/
├── app/
│   ├── __init__.py
│   └── app.py          # Main app with PyGWalker integration
├── rxconfig.py         # Reflex configuration
└── .gitignore

The computation setting determines where data queries are executed. Choosing the right mode depends on your data size and environment:

• browser: All data is sent to the client (browser) and computed there. Best for small datasets.
• kernel: A local DuckDB engine running within the Python process answers queries on demand. This is the recommended mode for large datasets because the frontend parses the Graphic Walker DSL to SQL, and only aggregated results are sent across the boundary.
• cloud: Uses Kanaries cloud for computation.

For users looking to move beyond quick scripts and master real-world workflows, the tutorials/ directory provides in-depth, step-by-step learning materials. Unlike the concise scripts in /examples, these tutorials focus on progressive learning and best practices.

The primary resource is complete_tutorial.ipynb, which covers:

• Environment setup and initialization
• Core chart types and interactions
• Data exploration workflows
• Real-world use cases (e.g., sales analytics, segmentation, experimentation)
• Performance tips and recommended patterns.

To set up the React frontend located in the app/ directory, you need to install dependencies and build the bundles.

Prerequisites:

• Node.js 22.x
• Yarn 1.x

Steps:

1. Navigate to the app/ directory.
2. Install dependencies using yarn install.
3. Build the frontend bundles using yarn build.

Note: Built assets are written to pygwalker/templates/dist/. For faster local iteration on the main app bundle specifically, use yarn build:app. This command is faster but does not perform TypeScript checking or build auxiliary DSL conversion bundles.

Since version 0.1.4.9, pygwalker supports Streamlit environments. You can enable it by passing the env parameter to the walk function.

pyg.walk(df, env='Streamlit')

For better performance and to save your work, use the following parameters in pyg.walk():

• spec: A path to a JSON file that saves the chart state. Note: You must click the 'Save' button in the UI to persist changes to this file; auto-save is not yet supported.
• kernel_computation: Set to True to use DuckDB as the calculation engine. This allows you to explore much larger datasets (up to 100 GB).

df = pd.read_csv('./bike_sharing_dc.csv')
walker = pyg.walk(
    df,
    spec="./chart_meta_0.json",    # Saves chart state to this JSON file
    kernel_computation=True,       # Uses DuckDB for datasets up to 100 GB
)