Pyecharts

2.1.0 · active · verified Mon Apr 13

Pyecharts is a powerful and flexible Python library designed to generate interactive ECharts-based visualizations. It provides a Pythonic interface to over 30 chart types, making it easier to create stunning and interactive data visualizations for web pages, Jupyter notebooks, and other Python frameworks. The library is actively maintained, with the current stable version being 2.1.0, released in February 2026, and regular updates incorporating new ECharts features.

Warnings

breaking Pyecharts v2.1.0 introduces compatibility with ECharts 6.x. This update may lead to breaking changes compared to ECharts 5.x, including modifications to the default theme, legend positions (now defaulting to the bottom), and subtle shifts in Cartesian axis labels if they previously overflowed or overlapped. Users migrating from versions <=2.0.9 (which supported ECharts 5.x) should review their chart configurations.
Fix: Review chart configurations and ECharts 6.x upgrade guide for changes in default themes, component positioning, and API updates. For styling, explicit `theme_opts` and `pos_top`, `pos_left` for legends can help restore previous layouts. The original ECharts documentation provides detailed migration steps from v5 to v6.
breaking Pyecharts V1 and V2 (including current v2.x) require Python 3.7 or newer. Earlier versions (v0.5.x) supported Python 2.7 and 3.4+. Attempting to use pyecharts v1+ in older Python environments will result in import errors or unexpected behavior.
Fix: Ensure your Python environment is version 3.7 or higher. Upgrade Python if necessary, or use a virtual environment with a compatible Python version.
gotcha Map chart data (e.g., world maps, Chinese provinces) is not bundled with the `pyecharts` core package since v0.3.2. Users must install separate `echarts-*-pypkg` extension packages for the specific map data they need (e.g., `pip install echarts-countries-pypkg`).
Fix: Install the relevant map data package using pip, for example, `pip install echarts-countries-pypkg` for world maps or `echarts-china-provinces-pypkg` for Chinese provincial data.
gotcha Exporting charts as static images (PNG, JPEG, PDF, SVG) requires the `pyecharts-snapshot` library along with a rendering backend like `pyppeteer` (which requires Node.js) or `selenium` (which requires a WebDriver). Without these, `chart.render()` will only output HTML, and image export methods will fail.
Fix: Install `pyecharts-snapshot` (`pip install pyecharts-snapshot`) and its chosen backend (e.g., `pip install snapshot-pyppeteer` and ensure Node.js is installed on your system).
gotcha When working with `numpy` arrays or `pandas` Series/DataFrames, `pyecharts` expects data to be in standard Python list formats. While v2.0.5 added better error messages, passing non-native data structures directly can still lead to unexpected behavior or errors if not explicitly converted (e.g., using `.tolist()`).
Fix: Convert `numpy` arrays or `pandas` Series/DataFrames to standard Python lists before passing them to `pyecharts` chart methods (e.g., `add_xaxis(data.tolist())`, `add_yaxis(name, values.tolist())`).
gotcha By default, `chart.render('filename.html')` saves the chart as an HTML file with embedded JavaScript dependencies. For displaying charts directly within Jupyter notebooks or similar environments, `chart.render_notebook()` is often preferred. For `Page` objects, the `is_embed_js=True` parameter can be used to explicitly embed all JavaScript resources into a single HTML file for offline use.
Fix: Use `chart.render_notebook()` for Jupyter environments. When generating standalone HTML files, be aware of the `is_embed_js` option on `Page` and `InitOpts` for controlling JavaScript embedding for offline access or smaller file sizes.

Install

pip install pyecharts Install stable version

Imports

Bar
```
from pyecharts.charts import Bar
```
options
```
from pyecharts import options as opts
```
ThemeType
```
from pyecharts.globals import ThemeType
```

Quickstart

This quickstart code creates a simple interactive bar chart using Pyecharts, adds two data series, and saves the chart as an HTML file named 'my_first_chart.html' in the current directory. This HTML file can then be opened in any web browser.

from pyecharts.charts import Bar
from pyecharts import options as opts

# Create a Bar chart instance
bar = (
    Bar()
    .add_xaxis(["Shirt", "Sweater", "Tie", "Pants", "T-shirt", "Jacket"])
    .add_yaxis("Seller A", [10, 20, 30, 40, 50, 60])
    .add_yaxis("Seller B", [15, 25, 35, 45, 55, 65])
    .set_global_opts(
        title_opts=opts.TitleOpts(title="ECharts Bar - Basic"),
        legend_opts=opts.LegendOpts(pos_left='center')
    )
)

# Render the chart to an HTML file
bar.render("my_first_chart.html")
print("Chart saved to my_first_chart.html")

view raw JSON →