pyecharts: Rendering ECharts Charts from Python

What pyecharts solves for Python users

Apache ECharts is a JavaScript charting library. Using it directly means writing JavaScript, wiring up a DOM container, and keeping your data pipeline in one language while your chart configuration lives in another. pyecharts removes that split. The README frames the motivation plainly: ECharts has good interactivity and careful chart design, Python is expressive and good at data processing, so the library sits between them.

The audience is the analyst or backend developer who already has data in Python and wants a chart that a browser can pan, zoom and hover. The README lists 30+ chart types, integration with Jupyter Notebook, JupyterLab and marimo, and integration with Flask, Sanic and Django. It also lists 400+ map files and native Baidu map support, which matters if your data is geographic and Chinese-market oriented.

The output is HTML, not a bitmap. That single fact drives most of the decisions below.

How the chainable API builds an ECharts option tree

The V1 and V2 APIs are built around method chaining. You instantiate a chart class from pyecharts.charts, call add_xaxis and add_yaxis to attach data, then set_global_opts and set_series_opts to attach configuration. Each call returns the chart object, so the calls stack.

The README is explicit that chaining is not mandatory: developers who dislike chaining can call the methods one at a time on a named variable. Both forms produce the same object.

Internally the chart accumulates a configuration tree that mirrors the ECharts option object, then renders it through a Jinja2 template into an HTML file. Jinja2 is a hard dependency, listed in requirements.txt alongside prettytable and simplejson. The pyproject.toml declares the same three as runtime dependencies and requires Python 3.7 or newer.

Version history matters here. The README states that v0.5.x and V1 are incompatible and that V1 is a new version; V2 renders on ECharts 5.4.1 or later while keeping the V1 documentation and example locations. The v0.5.x line, which supported Python 2.7 and 3.4+, is no longer maintained and lives on the 05x branch with documentation at 05x-docs.pyecharts.org. If you find a tutorial online, check which API it targets before copying it.

Installing pyecharts and rendering your first bar chart

The README gives pip as the primary install path, with the -U flag to upgrade an existing installation.

# 安装 v1 以上版本
$ pip install pyecharts -U

A source install is also documented: clone the repository, run pip install -r requirements.txt, then python setup.py install. The repository additionally carries a uv.lock and a Makefile whose build target runs uv build, so the maintainers use uv for development, though that is not presented as the user-facing install route.

The README's first example builds a grouped bar chart from two series and writes an HTML file. Copy it as-is to confirm the install works.

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

# V1 版本开始支持链式调用
bar = (
    Bar()
    .add_xaxis(["衬衫", "毛衣", "领带", "裤子", "风衣", "高跟鞋", "袜子"])
    .add_yaxis("商家A", [114, 55, 27, 101, 125, 27, 105])
    .add_yaxis("商家B", [57, 134, 137, 129, 145, 60, 49])
    .set_global_opts(title_opts=opts.TitleOpts(title="某商场销售情况"))
)
bar.render()

Running this writes an HTML file in the working directory. Open it in a browser and you should see two bar series side by side with a title. The chart is interactive because the browser is running ECharts, not because Python drew anything.

If you need a PNG instead, the README's second example uses make_snapshot from pyecharts.render together with a driver imported from snapshot_selenium. The README notes that snapshot-selenium or snapshot-phantomjs must be installed first; pyproject.toml exposes these as the optional extras selenium, phantomjs and pyppeteer.

from snapshot_selenium import snapshot as driver

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


def bar_chart() -> Bar:
    c = (
        Bar()
        .add_xaxis(["衬衫", "毛衣", "领带", "裤子", "风衣", "高跟鞋", "袜子"])
        .add_yaxis("商家A", [114, 55, 27, 101, 125, 27, 105])
        .add_yaxis("商家B", [57, 134, 137, 129, 145, 60, 49])
        .reversal_axis()
        .set_series_opts(label_opts=opts.LabelOpts(position="right"))
        .set_global_opts(title_opts=opts.TitleOpts(title="Bar-测试渲染图片"))
    )
    return c

# 需要安装 snapshot-selenium 或者 snapshot-phantomjs
make_snapshot(driver, bar_chart().render(), "bar.png")

That path drives a real browser through snapshot-selenium. The README does not document what happens when no browser binary is present.

Where pyecharts is the wrong tool

Image export is the clearest limitation. The README's own example for generating a picture imports a Selenium-backed snapshot driver, and the optional dependency list confirms that snapshot-selenium, snapshot-phantomjs or snapshot-pyppeteer is required. A server-side job that must emit PNGs therefore needs a browser engine in the image. If your pipeline runs in a minimal container with no Chrome or PhantomJS, the HTML path still works and the image path does not.

There is also a version cliff. The README states v0.5.x and V1 are incompatible, and that v0.5.x is no longer maintained. Code written against the old API will not run against V1 or V2 without rewriting. The project's own classifiers list Python 3.7 through 3.14, and requires-python is >=3.7, so Python 2.7 users have no supported path forward.

Finally, pyecharts is a configuration layer, not a rendering engine. Anything ECharts cannot draw, pyecharts cannot draw. If your requirement is a server-rendered static image with no JavaScript at any stage, the architecture is pointed the wrong way.

pyecharts vs plotly: HTML output against a broader rendering stack

The two libraries overlap in the obvious place: both let a Python user produce an interactive chart without writing JavaScript. The difference is what they do with the result.

pyecharts renders through Jinja2 templates into HTML and hands the drawing to ECharts in the browser. Its optional extras exist specifically to bolt a browser on for snapshot export. Its map story is unusually deep, with the README claiming 400+ map files and native Baidu map support.

A general-purpose plotting library such as plotly typically offers a static image path through a separate renderer, and its chart vocabulary is tied to its own JavaScript implementation rather than to ECharts. If your team already standardizes on ECharts themes, or your users expect the ECharts interaction model, that is the reason to pick pyecharts. If you need the same figure to come out as an SVG or PNG without a browser dependency, pyecharts is the harder route.

The README also points to two sibling projects in the same style, py-vchart and py-antv, which is a useful signal that the ECharts-to-Python pattern has more than one implementation.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-04. Releases have been paced rather than constant: v2.1.0 on 2026-02-10, v2.0.9 on 2025-10-10, and v2.0.8 on 2025-01-24. The gap between v2.0.8 and v2.0.9 is roughly nine months, so plan upgrades around releases rather than expecting a continuous stream.

Versioning is handled by setuptools_scm with the guess-next-dev scheme, and the version is read from pyecharts/_version.py in setup.py. That means a source checkout without proper git tags can produce an unexpected version string.

The licence is MIT, declared in pyproject.toml as license = {text = "MIT"} and shipped as a LICENSE file at the repository root. MIT is permissive and imposes no copyleft obligation on your own code. Note the transitive dependency surface: jinja2, prettytable and simplejson at runtime, and optionally snapshot-selenium, snapshot-phantomjs or snapshot-pyppeteer for images. Those snapshot packages carry their own licences and their own browser requirements, which is where the real operational cost sits. This is a description of what the repository declares, not legal advice.

The upgrade cost is concentrated at the v0.5.x to V1 boundary, which the README calls incompatible. Within V1 and V2 the README presents the API as continuous, with V2 changing the underlying ECharts version to 5.4.1+.

Editorial conclusion

Adopt pyecharts if your output is an HTML page, a notebook, or a Flask, Sanic or Django view, and your Python is 3.7 or newer. Do not adopt it if you need PNG or PDF output in a headless build with no browser: image export depends on snapshot-selenium, snapshot-phantomjs or snapshot-pyppeteer, and the README does not document a fallback. Before committing, check which ECharts version your target environment can load, confirm whether your code is on the v0.5.x API or the V1 chainable API, and verify that the chart types you need appear in the gallery.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. pyecharts/pyecharts on GitHub
4. README
5. Releases