Skip to content
Get packs

Guide · Open source

How to use pyecharts: install, make charts and embed them

Updated · written with AI from the project's own documentation and checked against our catalogue data

pyecharts is an open-source Python library that lets you build interactive charts without writing JavaScript. It wraps Apache ECharts and outputs HTML charts that you can open in a browser, display in Jupyter or marimo notebooks, or embed in web frameworks such as Flask and Django. This guide shows you how to install it, render your first chart, and use it in notebooks and web apps.

pyechartspyecharts/pyecharts · ★ 15.8k · MIT

Quick start

  1. 1Check your Python version. Confirm you have Python 3.7 or newer installed.
  2. 2Install pyecharts. Run pip install pyecharts -U in your terminal.
  3. 3Import a chart type. Import Bar or another chart class from pyecharts.charts, and options from pyecharts.
  4. 4Add your data. Set the x-axis labels with add_xaxis() and add one series per add_yaxis() call.
  5. 5Set options. Use set_global_opts() with opts.TitleOpts to add a title and other settings.
  6. 6Render the chart. Call render() to write an HTML file and open it in your browser.

What you need before you install pyecharts

pyecharts is a Python package, so you need Python installed first. The current line requires Python 3.7 or newer. The README notes that the older 0.5.x line supports Python 2.7 and 3.4+, but that line is no longer maintained, so new projects should use the current version.

  • Python 3.7 or newer
  • pip, the Python package installer

Install pyecharts with pip

Install or upgrade pyecharts with pip using the command from the project README. The -U flag upgrades the package if it is already installed.

pip install pyecharts -U

Make your first chart and save it as HTML

Import the chart type you need from pyecharts.charts and the options module. Build the chart with chained method calls, or call the methods one by one if you prefer. Calling render() writes the chart to an HTML file that you can open in a browser. The example below builds a bar chart comparing two sellers across seven product categories.

  • Use add_xaxis() to set the category labels.
  • Use add_yaxis() once per data series.
  • Use set_global_opts() with opts.TitleOpts to set the title.
  • Call render() to produce the HTML file.
from pyecharts.charts import Bar from pyecharts import options as opts 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()

Save a chart as an image

The README shows how to export a chart as a PNG using make_snapshot. You pass it a snapshot driver, the rendered HTML file, and the output file name. The README says you need to install snapshot-selenium or snapshot-phantomjs for this to work.

  • Install snapshot-selenium or snapshot-phantomjs first.
  • Import snapshot from the driver package you installed and pass it to make_snapshot.
from snapshot_selenium import snapshot as driver from pyecharts.render import make_snapshot make_snapshot(driver, bar_chart().render(), "bar.png")

Use pyecharts in Jupyter, JupyterLab or marimo

The project states that it supports mainstream notebook environments, including Jupyter Notebook, JupyterLab and marimo, so charts can appear inline next to your analysis. The README includes screenshots for Jupyter Notebook and JupyterLab but does not give separate setup steps for each, so check the official documentation at pyecharts.org for notebook-specific details.

  • Jupyter Notebook
  • JupyterLab
  • marimo

Embed charts in Flask, Sanic or Django

pyecharts can be added to web frameworks such as Flask, Sanic and Django. The README lists these as supported integrations and shows a demo animation, but the source excerpt does not include the integration code, so refer to the documentation at pyecharts.org for working examples.

  • Flask
  • Sanic
  • Django

Make maps with the bundled map files

The README says pyecharts ships with more than 400 map files and supports native Baidu Maps for geographic data. The project's feature list and demo gallery include map, geo and bmap examples. Use the pyecharts gallery repository to see how these charts are built.

  • Bundled map files for geographic charts
  • Baidu Maps support, as described in the README
  • Examples in the pyecharts-gallery repository

What people use it for

  • Analysts who want interactive bar or line charts from a Python script.
  • Jupyter or marimo users who want charts displayed inline next to their analysis.
  • Developers adding charts to a Flask, Sanic or Django web app.
  • People building maps from the bundled map files.

Frequently asked questions

Is pyecharts free to use?

Yes. The project is licensed under the MIT License, as shown in the README and its badge. The MIT License generally allows use, modification and distribution, so check the license text for full terms.

What Python version does pyecharts need?

The current version requires Python 3.7 or newer, according to the README. The older 0.5.x line supported Python 2.7 and 3.4+, but the README says that line is no longer maintained.

How do I install pyecharts?

Run pip install pyecharts -U in your terminal. The -U flag upgrades an existing installation to the latest version. The README also describes a source install using git clone and pip install -r requirements.txt.

Can pyecharts run in Jupyter notebooks?

Yes. The README says it supports Jupyter Notebook, JupyterLab and marimo. Screenshots in the README show charts in Jupyter Notebook and JupyterLab.

How does pyecharts compare to Plotly or Matplotlib?

The source does not include a comparison or benchmark. It does list Plotly, Matplotlib, Bokeh and Altair as comparable projects. pyecharts is specifically a wrapper around Apache ECharts, so it suits users who want ECharts-style interactive charts from Python.

Why does saving a PNG fail?

The README says make_snapshot needs snapshot-selenium or snapshot-phantomjs installed. If you have not installed one of these, install it first. The source does not list other troubleshooting steps, so check the documentation at pyecharts.org.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

pyecharts suits Python users who analyze data and want interactive ECharts charts without writing JavaScript, especially in notebooks or Flask, Sanic and Django apps. It is a weaker choice if you need the newest JavaScript-only ECharts features, a non-Python frontend stack, or the unmaintained 0.5.x line.

Install options & downloads