Altair Python: Install, First Chart and Vega-Lite Basics

Altair is a declarative statistical visualization library for Python. You describe what a chart should show (which data, which mark, which columns map to which visual channels) and Altair turns that description into a Vega-Lite JSON specification, which a viewer renders. This guide is for researchers and analysts who work in Python and want to install Altair, make a first chart, read the specification it produces, and save the result. Sources are the official Altair documentation and the PyPI project page, read on 2026-11-08.

What Altair is used for in research

According to its documentation, the main purpose of Altair is to convert plot specifications into a JSON string that conforms to the Vega-Lite schema (Altair: Starting with Altair). That design has one practical consequence for research work: the chart is defined by a small, text-based specification rather than by a sequence of drawing commands. The specification can be stored next to the data and the analysis code, which supports the kind of reproducibility that journals and funders increasingly ask for.

It differs in approach from the imperative plotting libraries covered elsewhere on this site. In Matplotlib-style code you build a figure step by step (see histograms in Matplotlib and pie charts in Python); in Altair you declare a mapping from data columns to visual properties. The same grammar-of-graphics idea is used by ggplot2 in R (see ggplots in R).

Install Altair from the official source

The Altair installation page lists these commands (Altair: Installation):

• pip install "altair[all]" installs Altair with its optional dependencies.
• conda install -c conda-forge altair-all is the conda equivalent. Omitting [all] (pip) or -all (conda) installs the minimal package.
• pip install "altair[save]" adds support for saving charts as offline HTML and as PNG, SVG or PDF.
• In a Pyodide environment: import micropip then await micropip.install("altair").

The PyPI page for altair showed version 6.3.0 (released 15 September 2026) on 2026-11-08, with a BSD license, the description “A declarative statistical visualization library for Python”, a Requires-Python value of 3.11 or later, and the extras all, dev, doc and save (PyPI: altair). Check the PyPI page for the current version before pinning one in a project.

Make your first chart, step by step

The Altair tutorial assumes a Jupyter-style environment such as JupyterLab, Colab or VS Code, where charts display automatically. The steps below follow the tutorial’s own example.

1. Create a pandas DataFrame and import Altair.

   import pandas as pd
   data = pd.DataFrame({'a': list('CCCDDDEEE'),
                        'b': [2, 7, 4, 1, 2, 6, 8, 4, 7]})
   import altair as alt

2. Wrap the data in a Chart and choose a mark. alt.Chart(data).mark_point() draws one point per row of the data, all plotted on top of each other because nothing is encoded yet.
3. Encode columns as channels.

   alt.Chart(data).mark_point().encode(
       x='a',
       y='b'
   )

4. Aggregate inside the encoding. The aggregate is written in the column identifier:

   alt.Chart(data).mark_bar().encode(
       x='a',
       y='average(b)'
   )

   Swapping the two (y='a', x='average(b)') gives a horizontal bar chart.

5. Set types explicitly when needed. The shorthand is field:type, so 'average(b):Q' is equivalent to alt.Y(field='b', type='quantitative', aggregate='average'). In the tutorial, N means nominal (unordered categories) and Q means quantitative (real-valued).

Output and how to read it

The visible output is the rendered chart. The underlying output is the specification: calling chart.to_json() returns the Vega-Lite JSON that Altair generated. According to the tutorial it includes the $schema, the data and datasets sections, an encoding block and a mark block. The shorthand encode(x='a') expands into an object with a field and a type, and y='average(b)' adds an aggregate key. Reading that JSON is the quickest way to confirm that Altair interpreted your column types as you intended.

Save a chart

The saving documentation gives these options (Altair: Saving Charts):

Format	Command	Extra requirement
JSON specification	chart.save('chart.json') or chart.to_json()	None
HTML (loads Vega libraries from a CDN)	chart.save('chart.html')	Internet connection needed to display
HTML that works offline	chart.save('chart.html', inline=True)	vl-convert
PNG, SVG, PDF	chart.save('chart.png'), .svg, .pdf	vl-convert (pip install vl-convert-python)

The format is chosen from the file extension. PNG resolution can be set with ppi=200 (default 72) or scale_factor=2. The documentation notes that the altair_saver package is no longer maintained and recommends vl-convert instead.

Troubleshooting

• The install fails or the package is not found. The PyPI page lists Python 3.11 or later as required for the current release. Check python --version and use a newer interpreter or environment.
• Saving to PNG, SVG, PDF or offline HTML raises an error. These formats need vl-convert. Install it with pip install vl-convert-python or install Altair with the [save] extra.
• The chart does not appear. The tutorial assumes a Jupyter-style environment. In other interfaces, check how Altair charts are displayed there, or save to HTML and open the file.
• A column is treated as the wrong kind of data. Add the type to the shorthand ('b:Q', 'a:N') or use alt.Y(...) with an explicit type, then inspect to_json().

Free alternatives

Altair is free and BSD-licensed. Other open options covered on this site include:

Tool	Language	Style	CASRAI guide
Bokeh	Python	Interactive plots for the browser	Bokeh in Python
Matplotlib	Python	Imperative, figure-building	Histograms in Matplotlib
ggplot2	R	Grammar of graphics	ggplots in R

For a side-by-side of two of these libraries, see Plotly vs Matplotlib.

FAQ

What is Altair in Python?

A declarative statistical visualization library. You declare the data, mark and encodings, and Altair generates a Vega-Lite JSON specification that is rendered as a chart.

How do I install Altair?

Run pip install "altair[all]", or conda install -c conda-forge altair-all. Add the [save] extra if you need to export PNG, SVG, PDF or offline HTML.

Which Python version does Altair need?

PyPI lists Python 3.11 or later for version 6.3.0, as shown on 2026-11-08.

How do I save an Altair chart as an image?

Install vl-convert, then call chart.save('chart.png') (or .svg, .pdf).

Sources

• Altair documentation: Installation (read 2026-11-08)
• Altair documentation: Starting with Altair (read 2026-11-08)
• Altair documentation: Saving Charts (read 2026-11-08)
• PyPI: altair (read 2026-11-08)