Vega-Altair: A declarative statistical visualization library for Python

6.0.0 · active · verified Sat Mar 28

Altair is a declarative statistical visualization library for Python, built on top of the powerful Vega-Lite JSON specification. It offers a simple, friendly, and consistent API for creating a wide range of interactive and aesthetically pleasing statistical charts with a minimal amount of code. The library is actively developed, with a current stable version of 6.0.0 and weekly pre-release builds.

Warnings

breaking Altair 6.0.0 officially removes support for Python 3.8. Users should upgrade to Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or higher. Review `pyproject.toml` or `setup.cfg` for `requires_python` constraints.
breaking Altair 6.0.0 is compiled against Vega-Lite version 6. While largely backward compatible, some advanced or undocumented Vega-Lite features might behave differently or require updates if you were directly manipulating the underlying JSON spec.
Fix: Consult the Vega-Lite 6 release notes for any specific breaking changes relevant to your custom specifications. Test existing complex charts after upgrading.
breaking The recommended way to access built-in example datasets changed from `from vega_datasets import data` to `from altair.datasets import data` in Altair 6.0.0. Some column names in these datasets might also have changed (e.g., spaces instead of underscores).
Fix: Update import statements to `from altair.datasets import data`. If encountering `KeyError` for column names, check the dataset documentation or inspect the DataFrame for updated column names.
gotcha Altair charts are primarily designed for display in Jupyter environments (Notebook, Lab, VS Code with Jupyter extension). Outside of these, you may need to configure a specific renderer (e.g., 'mimetype', 'html', 'json', 'altair_saver') to display or save charts.
Fix: For non-Jupyter environments, ensure you explicitly call `chart.save('chart.html')`, `chart.to_json()`, or configure a renderer like `alt.renderers.enable('altair_saver')` (requires `vl-convert-python`).

Install

pip install altair Base Installation
pip install "altair[all]" With all optional dependencies (e.g., pandas, vega_datasets, vl-convert)

Imports

Chart
```
import altair as alt
```
Standard convention for Altair imports.
data
```
from altair.datasets import data
```
As of Altair v6.0.0, the recommended way to access built-in datasets is via `altair.datasets`. The `vega_datasets` package is still functional but less integrated for new examples.

Quickstart

This quickstart demonstrates how to create a basic bar chart using Altair with a pandas DataFrame. It defines a DataFrame, then uses `alt.Chart()` to specify the data, `mark_bar()` to choose the chart type, and `encode()` to map data columns to visual properties (x and y axes). The `.show()` method attempts to render the chart in a compatible environment.

import altair as alt
import pandas as pd

# Sample data
data = pd.DataFrame({
    'a': ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I'],
    'b': [28, 55, 43, 91, 81, 53, 19, 87, 52]
})

# Create a simple bar chart
chart = alt.Chart(data).mark_bar().encode(
    x='a',
    y='b'
)

chart.show()

view raw JSON →