pyecharts-express 0.2.1

A plotly-express style API for pyecharts — build ECharts with concise, dataframe-friendly calls.

pyecharts-express

A plotly-express style API for pyecharts (ECharts).

Pass a pandas DataFrame or list[dict] directly and build charts with intuitive keywords like x / y / color. Every function returns a plain pyecharts Chart object, so the standard pyecharts API (.render(), .render_notebook(), Grid composition, etc.) stays fully available afterwards.

---

Features

• 📊 plotly-express style signatures — bar(df, x="city", y="pop", color="region")
• 🐼 pandas-friendly — accepts DataFrame / list[dict] / dict
• 🎨 pyecharts-compatible — returns a raw Chart, freely customizable
• 🧩 covers the plotly-express chart surface (unsupported ones raise a clear NotImplementedError)
• 🪶 lightweight — a thin wrapper layer; the full power of pyecharts is reachable
• 🧪 tested — pytest covers every chart type (54 tests)

---

Installation

pip install pyecharts-express
# or
uv add pyecharts-express

---

Quick start

import pandas as pd
import pyecharts_express as px

df = pd.DataFrame({
    "city":   ["Tokyo", "Osaka", "Kyoto", "Nagoya"],
    "pop":    [139, 27, 15, 23],
    "region": ["Kanto", "Kansai", "Kansai", "Chubu"],
})

chart = px.bar(df, x="city", y="pop", color="region", title="Population")
chart.render("bar.html")
# chart.render_notebook()   # inline display in Jupyter

---

Chart reference

pyecharts-express mirrors the major plotly-express functions. Functions with no pyecharts equivalent raise NotImplementedError with guidance.

Basic

Function	Description	Key args
px.bar	Bar chart	x, y, color, stack
px.line	Line chart	x, y, color, smooth
px.scatter	Scatter plot	x, y, color
px.area	Area chart	x, y, color, stack
px.funnel	Funnel chart	names, values, sort
px.funnel_area	Area funnel	names, values

Part-of-whole

Function	Description	Key args
px.pie	Pie chart	names, values, hole, rose_type
px.sunburst	Sunburst	path or (names, parents), values
px.treemap	Treemap	path or (names, parents), values
px.icicle	Icicle	path or (names, parents), values

Distributions

Function	Description	Key args
px.histogram	Histogram	x, bins, density
px.box / px.boxplot	Box plot	x, y
px.violin	❌ unsupported (no pyecharts equivalent)	—
px.strip	❌ unsupported	—
px.density_heatmap	2D histogram	x, y, bins
px.density_contour	❌ unsupported (no pyecharts equivalent)	—

Polar

Function	Description	Key args
px.bar_polar	Polar bar	theta, r, color, stack
px.line_polar	Polar line	theta, r, color
px.scatter_polar	Polar scatter	theta, r, color

Maps

Function	Description	Key args
px.map_choropleth / px.choropleth	Choropleth map	names, values, maptype
px.scatter_geo	Geo scatter	lon, lat, maptype
px.line_geo	Geo line	lon, lat, maptype

Multidimensional

Function	Description	Key args
px.scatter_matrix	Scatter plot matrix (SPLOM)	dimensions, color
px.parallel_coordinates	Parallel coordinates	dimensions, color
px.parallel_categories	Parallel categories	dimensions, color

Misc

Function	Description	Key args
px.radar	Radar chart	indicators, series
px.sankey	Sankey diagram	source, target, values
px.gauge	Gauge	values, min_, max_
px.graph	Network graph	source, target
px.themeriver	Theme river	date, value, category
px.calendar_heatmap	Calendar heatmap	date, value, year
px.wordcloud	Word cloud	words, values

---

Hierarchical data

sunburst / treemap / icicle accept two input shapes:

# 1. path (ordered hierarchy columns)
px.sunburst(df, path=["region", "pref", "city"], values="population")

# 2. names / parents (plotly style)
px.sunburst(df, names="node", parents="parent", values="value")

---

Input shapes

Every function accepts:

# 1. pandas DataFrame
px.bar(df, x="city", y="pop")

# 2. list[dict] (records)
px.line([{"x": 1, "y": 2}, {"x": 2, "y": 4}], x="x", y="y")

# 3. dict (column-oriented)
px.bar({"x": ["a", "b"], "y": [1, 2]}, x="x", y="y")

---

Common options

px.bar(
    df, x="city", y="pop",
    title="Title",
    xaxis_name="City",
    yaxis_name="Population",
    width="800px",
    height="500px",
    theme="dark",
)

---

Interop with pyecharts

The return value is a raw pyecharts Chart, so you can extend it with the standard API:

chart = px.bar(df, x="city", y="pop")
chart.set_series_opts(label_opts=opts.LabelOpts(is_show=True))
chart.render("custom.html")

Compose multiple charts with Grid / Page:

from pyecharts.charts import Page
page = Page()
page.add(px.bar(df, x="city", y="pop"))
page.add(px.line(df, x="city", y="pop"))
page.render("page.html")

---

Development

git clone https://github.com/tetsuji16/pyecharts-express
cd pyecharts-express
uv sync
uv run pytest

---

License

MIT