Vega-Altair: A declarative statistical visualization library for Python

Common errors

• ModuleNotFoundError: No module named 'altair'

  cause The Altair library is not installed in the Python environment.
  fix Install Altair using pip: `pip install altair`.

• AttributeError: module 'altair' has no attribute 'selection_point'

  cause The 'selection_point' attribute is not available in the installed version of Altair.
  fix Upgrade Altair to the latest version: `pip install --upgrade altair`.

• AttributeError: module 'altair' has no attribute 'Chart'

  cause A local file named 'altair.py' is shadowing the Altair library.
  fix Rename or remove the local 'altair.py' file to avoid the naming conflict.

• AttributeError: module 'jsonschema' has no attribute 'Draft7Validator'

  cause An outdated version of the 'jsonschema' library is installed.
  fix Upgrade 'jsonschema' to a compatible version: `pip install 'jsonschema>=3.0,<4.0'`.

• ModuleNotFoundError: No module named 'altair.vegalite.v4'

  cause The installed version of Altair does not include the 'vegalite.v4' module.
  fix Ensure compatibility between Altair and dependent libraries by installing compatible versions or upgrading dependent libraries.

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`).
• breaking Building `vegafusion` (a dependency of Altair) on Alpine Linux environments may fail due to missing `glibc` or `libgcc` components required by Rust/Cargo build tools. This typically manifests as 'Error loading shared library libgcc_s.so.1: No such file or directory' errors during metadata generation.
  Fix: To resolve this, install `libgcc` and `libstdc++` in your Alpine environment or Dockerfile before installing Python packages that rely on Rust extensions. For example, using `apk add libgcc libstdc++`.

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
  wrong:

  from vega_datasets import data

  correct:

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