[English](README.md) | [Español](./docs/README.es.md) | [Français](./docs/README.fr.md) | [Deutsch](./docs/README.de.md) | [中文](./docs/README.zh.md) | [Türkçe](./docs/README.tr.md) | [日本語](./docs/README.ja.md) | [한국어](./docs/README.ko.md) | [Русский](./docs/README.ru.md)
> [!NOTE]
> The English README is the source of truth for the API reference, installation, and development instructions. Translated READMEs are community-maintained and may lag behind this file.
PyGWalker: A Python Library for Exploratory Data Analysis with Visualization
[**PyGWalker**](https://github.com/Kanaries/pygwalker) can simplify your Jupyter Notebook data analysis and data visualization workflow, by turning your pandas dataframe into an interactive user interface for visual exploration.
**PyGWalker** (pronounced like "Pig Walker", just for fun) is named as an abbreviation of "**Py**thon binding of **G**raphic **Walker**". It integrates Jupyter Notebook with [Graphic Walker](https://github.com/Kanaries/graphic-walker), an open-source alternative to Tableau. It allows data scientists to visualize / clean / annotates the data with simple drag-and-drop operations and even natural language queries.
https://github.com/Kanaries/pygwalker/assets/22167673/2b940e11-cf8b-4cde-b7f6-190fb10ee44b
> [!TIP]
> If you want more AI features, we also build [runcell](https://runcell.dev), an AI Code Agent in Jupyter that understands your code/data/cells and generate code, execute cells and take actions for you. It can be used in jupyter lab with `pip install runcell`
https://github.com/user-attachments/assets/9ec64252-864d-4bd1-8755-83f9b0396d38
Visit [Google Colab](https://colab.research.google.com/drive/171QUQeq-uTLgSj1u-P9DQig7Md1kpXQ2?usp=sharing), [Kaggle Code](https://www.kaggle.com/code/lxy21495892/airbnb-eda-pygwalker-demo) or [Graphic Walker Online Demo](https://graphic-walker.kanaries.net/) to test it out!
> If you prefer using R, check [GWalkR](https://github.com/Kanaries/GWalkR), the R wrapper of Graphic Walker.
> If you prefer a Desktop App that can be used offline and without any coding, check out [PyGWalker Desktop](https://kanaries.net/download?utm_source=pygwalker_github&utm_content=tip).
# Features
PyGWalker is a Python library that simplifies data analysis and visualization workflows by turning pandas, polars, and pyarrow table data into interactive visual interfaces.
It offers a variety of features that make it a powerful tool for data exploration:
- ##### Interactive Data Exploration:
- Drag-and-drop interface for easy visualization creation.
- Real-time updates as you make changes to the visualization.
- Ability to zoom, pan, and filter the data.
- ##### Data Cleaning and Transformation:
- Visual data cleaning tools to identify and remove outliers or inconsistencies.
- Ability to create new variables and features based on existing data.
- ##### Advanced Visualization Capabilities:
- Support for various chart types (bar charts, line charts, scatter plots, etc.).
- Customization options for colors, labels, and other visual elements.
- Interactive features like tooltips and drill-down capabilities.
- ##### Integration with Jupyter Notebooks:
- Seamless integration with Jupyter Notebooks for a smooth workflow.
- ##### Open-Source and Free:
- Available for free and allows for customization and extension.
# Getting Started
> Check our video tutorial about using pygwalker, pygwalker + streamlit and pygwalker + snowflake, [How to explore data with PyGWalker in Python
](https://youtu.be/rprn79wfB9E?si=lAsJn1cAQnb-EklD)
| [Run in Kaggle](https://www.kaggle.com/code/lxy21495892/airbnb-eda-pygwalker-demo) | [Run in Colab](https://colab.research.google.com/drive/171QUQeq-uTLgSj1u-P9DQig7Md1kpXQ2?usp=sharing) |
|--------------------------------------------------------------|--------------------------------------------------------|
| [](https://www.kaggle.com/code/lxy21495892/airbnb-eda-pygwalker-demo) | [](https://colab.research.google.com/drive/171QUQeq-uTLgSj1u-P9DQig7Md1kpXQ2?usp=sharing) |
## Setup pygwalker
Before using pygwalker, make sure to install the packages through the command line using pip or conda.
### pip
```bash
pip install pygwalker
```
> **Note**
>
> For an early trial, you can install with `pip install pygwalker --upgrade` to keep your version up to date with the latest release or even `pip install pygwalker --upgrade --pre` to obtain latest features and bug-fixes.
### Conda-forge
```bash
conda install -c conda-forge pygwalker
```
or
```bash
mamba install -c conda-forge pygwalker
```
See [conda-forge feedstock](https://github.com/conda-forge/pygwalker-feedstock) for more help.
## Use pygwalker in Jupyter Notebook
### Quick Start
Import pygwalker and pandas to your Jupyter Notebook to get started.
```python
import pandas as pd
import pygwalker as pyg
```
You can use pygwalker without breaking your existing workflow. For example, you can call up PyGWalker with the dataframe loaded in this way:
```python
df = pd.read_csv('./bike_sharing_dc.csv')
walker = pyg.walk(df)
```
That's it. Now you have an interactive UI to analyze and visualize data with simple drag-and-drop operations.
Cool things you can do with PyGwalker:
+ You can change the mark type into others to make different charts, for example, a line chart:
+ To compare different measures, you can create a concat view by adding more than one measure into rows/columns.
+ To make a facet view of several subviews divided by the value in dimension, put dimensions into rows or columns to make a facets view.
+ PyGWalker contains a powerful data table, which provides a quick view of data and its distribution, profiling. You can also add filters or change the data types in the table.
+ You can save the data exploration result to a local file
### Better Practices
There are some important parameters you should know when using pygwalker:
+ `spec_path`: local file path for saving/loading chart config.
+ `spec`: chart config object, JSON string, config ID, or remote URL.
+ `computation`: choose where data queries run. Use `"browser"` for frontend-only computation, `"kernel"` for local DuckDB-backed Python computation, `"cloud"` for Kanaries cloud computation, or omit it for the default automatic behavior.
+ `kernel_computation`: legacy boolean for using DuckDB as computing engine. Prefer `computation="kernel"` or `computation="browser"`; this legacy flag is scheduled for removal in PyGWalker 0.7.0.
+ `cloud_computation`: legacy boolean for Kanaries cloud computation. Prefer `computation="cloud"`; this legacy flag is scheduled for removal in PyGWalker 0.7.0.
+ `use_kernel_calc`: deprecated alias for kernel computation. Prefer `computation="kernel"` or `computation="browser"`; this legacy flag is scheduled for removal in PyGWalker 0.7.0.
```python
df = pd.read_csv('./bike_sharing_dc.csv')
walker = pyg.walk(
df,
spec_path="./chart_meta_0.json", # local file used to load and save chart state.
computation="kernel", # use DuckDB in the Python kernel for larger datasets.
)
```
For new code on the 0.6 line, prefer a reusable `Walker` object and choose where to render it:
```python
walker = pyg.Walker(df, spec_path="./chart_meta_0.json", computation="browser")
walker.show() # auto-detects notebook or script mode
html = walker.to_html()
html = pyg.to_html(walker)
```
See [PyGWalker 0.6 Release Notes](./docs/RELEASE_0_6.md) for the compatibility policy, deprecation timeline, and tested runtime support.
After exploring in the UI, export the current chart state as reproducible Python code:
```python
code = walker.to_code(dataset_name="df")
print(code)
```
If you have an older saved spec, migrate it to the current schema before committing it:
```python
migrated_spec = pyg.spec.migrate(open("./old_chart_meta.json").read())
```
### Example in local notebook
* Notebook Code: [Click Here](https://github.com/Kanaries/pygwalker-offline-example)
* Preview Notebook Html: [Click Here](https://pygwalker-public-bucket.s3.amazonaws.com/demo.html)
### Example in cloud notebook
* [Use PyGWalker in Kaggle](https://www.kaggle.com/code/lxy21495892/airbnb-eda-pygwalker-demo)
* [Use PyGWalker in Google Colab](https://colab.research.google.com/drive/171QUQeq-uTLgSj1u-P9DQig7Md1kpXQ2?usp=sharing)
### Programmatic Export of Charts
After saving a chart from the UI, you can retrieve the image directly from Python.
```python
walker = pyg.walk(df, spec_path="./chart_meta_0.json")
# edit the chart in the UI and click the save button
walker.save_chart_to_file("Chart 1", "chart1.svg", save_type="svg")
png_bytes = walker.export_chart_png("Chart 1")
svg_bytes = walker.export_chart_svg("Chart 1")
```
## Use pygwalker in Streamlit
Streamlit allows you to host a web version of pygwalker without figuring out details of how web application works.
Here are some of the app examples build with pygwalker and streamlit:
+ [PyGWalker + streamlit for Bike sharing dataset](https://pygwalkerdemo-cxz7f7pt5oc.streamlit.app/)
+ [Earthquake Dashboard](https://earthquake-dashboard-pygwalker.streamlit.app/)
```
…
```
If you already created a reusable `Walker`, Streamlit can render it directly:
```python
import pygwalker as pyg
from pygwalker.api.streamlit import StreamlitRenderer
walker = pyg.Walker(df, spec_path="./gw_config.json", computation="kernel")
renderer = StreamlitRenderer(walker)
renderer.explorer()
```
## [API Reference](https://pygwalker-docs.vercel.app/api-reference/jupyter)
### [pygwalker.walk](https://pygwalker-docs.vercel.app/api-reference/jupyter#walk)
| Parameter | Type | Default | Description |
|--------------------|-----------------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
| dataset | Union[DataFrame, pyarrow.Table, Connector, str, Walker] | - | DataFrame, pyarrow table, database connector, SQL/data source string, or reusable Walker object to explore. |
| gid | Union[int, str] | None | ID for the GraphicWalker container div, formatted as `gwalker-{gid}`. |
| env | Literal['JupyterAnywidget', 'Jupyter', 'JupyterWidget'] | 'JupyterAnywidget' | Notebook rendering environment. Use `JupyterAnywidget` or omit `env`; `Jupyter` and `JupyterWidget` are deprecated aliases to the anywidget transport and are scheduled for removal in PyGWalker 0.7.0. |
| field_specs | Optional[List[FieldSpec]] | None | Field specifications. They will be inferred from `dataset` if not specified.