pyecharts

library2.1.0pypypi✓ verified 24d ago

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.

data

pip install pyecharts

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYECHARTS

pyecharts

datapythonv2.1.0

Install

2.4s avg

Import

381ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.390s · 28.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.372s · 29MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bar

✓ from pyecharts.charts import Bar

options

✓ from pyecharts import options as opts

ThemeType

✓ from pyecharts.globals import ThemeType

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")

Debug

Known issues

breakingPyecharts 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.

affects: >=2.1.0

breakingPyecharts 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.

affects: >=1.0.0

gotchaMap 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.

affects: >=0.3.2

gotchaExporting 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).

affects: All versions

gotchaWhen 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())`).

affects: All versions

gotchaBy 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyecharts'

The 'pyecharts' library is not installed in your current Python environment or the environment where you are trying to run your code.

fix

Install the library using pip: `pip install pyecharts`

ImportError: cannot import name 'Bar' from 'pyecharts'

This error typically occurs when trying to import chart types (like `Bar`, `Line`, etc.) directly from the top-level `pyecharts` module. In pyecharts versions 1.x and later, chart classes are located within `pyecharts.charts`.

fix

Import chart types from `pyecharts.charts`: `from pyecharts.charts import Bar` (replace `Bar` with the desired chart type). You might also need to import `options` from `pyecharts` as `from pyecharts import options as opts`.

AttributeError: module 'pyecharts' has no attribute 'utils'

This error arises when trying to access a module or attribute, like `utils`, directly from the `pyecharts` top-level module, but its location or existence has changed in newer versions of the library.

fix

Ensure you are using the correct import paths for utility functions or specific modules. For common configurations, import `options` as `from pyecharts import options as opts`. If 'utils' is specifically needed, it might be in `pyecharts.commons.utils` or its functionality has been absorbed elsewhere.

Pyecharts chart not displaying in Jupyter/browser

Charts may not display correctly due to incorrect rendering methods for the specific environment (e.g., Jupyter Notebook, web page), issues with JavaScript dependencies, or incorrect configuration of the output. In Jupyter, not using `render_notebook()` or similar can lead to only HTML output.

fix

For Jupyter Notebooks, use the `.render_notebook()` method: `chart.render_notebook()`. For saving to an HTML file, use `chart.render('your_chart.html')`. Ensure `CurrentConfig.NOTEBOOK_TYPE` is set correctly if you are in environments like Jupyter Lab or VS Code Notebooks: `from pyecharts.globals import CurrentConfig, NotebookType; CurrentConfig.NOTEBOOK_TYPE = NotebookType.JUPYTER_LAB` (adjust `NotebookType` as needed).

ModuleNotFoundError: No module named 'pyecharts_snapshot'

The `pyecharts-snapshot` library, essential for exporting charts to static image formats (PNG/SVG/PDF) using `render_as_image`, is not installed.

fix

Install `pyecharts-snapshot` and ensure a compatible headless browser driver (e.g., `chromedriver-py`) is available: `pip install pyecharts-snapshot chromedriver-py`.

Upgrade

Version history

2.1.0latest on PyPI · released Feb 10, 2026

Audit

Dependencies

pyecharts-snapshotoptionalRequired for exporting charts as images (PNG, JPEG, PDF, SVG, etc.). It relies on browser automation tools like pyppeteer or selenium.

echarts-countries-pypkgoptionalOptional package for world map data. Other map packages (e.g., `echarts-china-provinces-pypkg`) are needed for specific regional maps.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/pyecharts/pyecharts ↗

packagehttps://pypi.org/project/pyecharts/ ↗

homepagehttps://pyecharts.org ↗