Displaying Charts in Various Frontends

Altair provides a high-level API for creating visualizations that are encoded as declarative JSON objects. To display a visualization, those JSON objects must be displayed using the Vega-Lite and Vega JavaScript packages. This step of displaying a Vega-Lite or Vega JSON object is encoding in a renderer abstraction. This section of the documentation describes renderers and how you can use them to display Altair visualizations.

You may need to install an additional Python/npm package to display Altair charts for a given frontend user-interface. See instructions for: Displaying in the Jupyter Notebook, Displaying in JupyterLab, Displaying in nteract and Displaying in Colab.

Vega-Lite/Vega versions

As of version 2.0, Altair includes support for multiple version of both Vega-Lite (2.x and 1.x) and Vega (3.x and 2.x) in a single Python package. The default usage, including all examples in this documentation, makes use of the newest available versions (Vega-Lite 2.X and Vega 3.X).

The vega-lite version used by default can be found as follows:

>>> import altair as alt
>>> alt.schema.SCHEMA_VERSION
'v2.3.0'

If you wish to use an older version of these libraries, see Importing Vega & Vega-Lite Versions for more information. We strongly recommend all users transition to Vega-Lite 2.x and Vega 3.x. These versions support many new features, are more stable, and Altair 2.0 works best with them.

For all users, the important point here is that you must have a renderer installed that works with the appropriate version.

Renderers

Altair displays visualizations using renderers. There are two aspects of renderers:

Renderer API

In Altair, a renderer is any function that accepts a Vega-Lite or Vega visualization specification as a Python dict, and returns a Python dict in Jupyter’s MIME Bundle format. The keys of the MIME bundle should be MIME types (such as image/png) and the values should be the data for that MIME type (text, base64 encoded binary or JSON). The type signature of a renderer is thus:

def renderer(spec: dict) -> dict:
    ...

Altair and various user-interfaces have standardized on a couple of custom MIME types for Vega and Vega-Lite:

  • Vega-Lite 2.x: application/vnd.vegalite.v2+json
  • Vega-Lite 1.x: application/vnd.vegalite.v1+json
  • Vega 3.x: application/vnd.vega.v3+json
  • Vega 2.x: application/vnd.vega.v2+json

The default renderers simply take a JSON spec and return a MIME bundle with one of these MIME types:

def default_renderer(spec):
    bundle = {}
    metadata = {}
    bundle['text/plain'] = '<VegaLite object>`
    bundle[mime_type] = 'application/vnd.vegalite.v2+json'
    return bundle, metadata

If a renderer needs to do custom display logic that doesn’t use Jupyter’s display system, it can return an empty MIME bundle dict:

def non_jupyter_renderer(spec):
    # Custom display logic that uses the spec
    ...
    # Return empty MIME bundle
    return {}

Altair offers an API to list the known renderers, register new ones and enable a given one. To return the registered renderers as a Python list:

>>> import altair as alt
>>> alt.renderers.names()
['default', 'json']

To enable the JSON renderer, which results in a collapsible JSON tree view in JupyterLab/nteract:

>>> alt.renderers.enable('json')

To register and enable a new renderer:

>>> alt.renderers.register('custom_renderer', custom_renderer)
>>> alt.renderers.enable('custom_renderer')

Renderers can also be registered using the entrypoints API of Python packages. For an example, see `ipyvega`_.

This same renderer objects exists separately on all of the Python APIs for Vega-Lite/Vega described in Importing Vega & Vega-Lite Versions.

Displaying in the Jupyter Notebook

To render Vega-Lite 2.x or Vega 3.x in the Jupyter Notebook (as mentioned above we recommend these versions), you will need to install and enable the `ipyvega`_ Python package using conda:

$ conda install vega --channel conda-forge

or pip:

$ pip install jupyter pandas vega
$ jupyter nbextension install --sys-prefix --py vega # not needed in notebook >= 5.3

For Vega-Lite 1.x or Vega 2.x, you will need to install and enable the `ipyvega`_ Python package using:

$ conda install vega --channel conda-forge

or pip:

$ pip install jupyter pandas vega
$ jupyter nbextension install --sys-prefix --py vega # not needed in notebook >= 5.3

Once you have installed one of these packages, enable the corresponding renderer in Altair:

alt.renderers.enable('notebook')

Displaying in JupyterLab

JupyterLab versions 0.32 and later include built-in support for Vega-Lite 2.x and Vega 3.x. These will work out of the box with Altair imported as:

import altair as alt

An extension is available with the older Vega-Lite 1.x and Vega 2.x renderers (labextension install requires nodejs):

conda install -c conda-forge nodejs  # if you do not already have nodejs installed
jupyter labextension install @jupyterlab/vega2-extension

Displaying in nteract

Current versions of nteract have Vega and Vega-Lite built-in, and will render Altair plots without any extra configuration.

Displaying in Colab

Google’s Colab is a cloud-based notebook backed by Google Drive. Colab comes with Altair pre-installed and with the 'colab' renderer enabled, so Altair will work out-of-the-box.

Working in non-Notebook Environments

The Vega-Lite specifications produced by Altair can be produced in any Python environment, but to render these specifications currently requires a javascript engine. For this reason, Altair works most seamlessly with the browser-based environments mentioned above.

If you would like to render plots from another Python interface that does not have a built-in javascript engine, you’ll need to somehow connect your charts to a second tool that can execute javascript.

Fortunately, most people have a web browser available, and Altair provides the Chart.serve() method which will seamlessly convert the plot to HTML, start a webserver serving that HTML, and open your system’s default web browser to view it.

For example, you can serve a chart to a web browser like this:

import altair as alt

# load a simple dataset as a pandas DataFrame
from vega_datasets import data
cars = data.cars()

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower',
    y='Miles_per_Gallon',
    color='Origin',
).interactive()

chart.serve()

The command will block the Python interpreter, and will have to be canceled with Ctrl-C to execute any further code.