Installation

To use Altair for visualization, you need to install two sets of tools

  1. The core Altair Package and its dependencies
  2. The renderer for the frontend you wish to use (i.e. Jupyter Notebook, JupyterLab, Colab, or nteract)

See the following instructions for your chosen frontend:

Quick Start: Altair + JupyterLab

We recommend installing Altair with JupyterLab. If you would like to use it with the classic notebook, see Quick Start: Altair + Notebook.

To install JupyterLab and Altair with pip, run the following commands:

$ pip install jupyterlab altair==2.0.0rc2
$ jupyter labextension install @jupyterlab/vega3-extension  # not needed for JupyterLab 0.32 or newer

Once this is finished, run:

$ jupyter lab

In the browser window that launches, under “Notebook” click the first available kernel (it should say “Python 2” or “Python 3” depending on which Python version you are running).

In the notebook that opens, you can run the following code to ensure everything is properly set up:

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalLength',
    y='petalWidth',
    color='species'
)

If the plot does not render, ensure you have installed the exact versions mentioned above, and if it still does not work see Trouble-shooting Altair with JupyterLab for help.

Once things are up and running, you may wish to go through the tutorials at Basic Statistical Visualization and Exploring Seattle Weather, read through the User Guide indexed in the left panel, or check out the Example Gallery for more ideas.

Quick Start: Altair + Notebook

Altair, the jupyter notebook, and their dependencies can be installed with pip. Note that rendering Altair plots in the notebook also requires the vega3 package to be installed and configured:

$ pip install notebook vega3 altair==2.0.0rc2
$ jupyter nbextension install --sys-prefix --py vega3 # not needed in notebook >= 5.3

Once the packages and extensions are installed, launch the notebook by running:

$ jupyter notebook

In the browser window that launches, click the New drop-down menu and select either “Python 2” or “Python 3”, depending on which version of Python you are using (note that the kernel you choose must match the kernel where you installed the vega3 extension).

In the notebook that opens, you can run the following code to ensure everything is properly set up:

import altair as alt
from vega_datasets import data

# for the notebook only (not for JupyterLab) run this command once per session
alt.renderers.enable('notebook')

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalLength',
    y='petalWidth',
    color='species'
)

Note

For the classic Jupyter notebook (not JupyterLab), each time you launch a notebook you must explicitly enable Altair rendering by running:

alt.renderers.enable('notebook')

If you neglect this step, charts will not be rendered, but instead displayed as a textual representation.

If the plot does not render, ensure you have installed the exact versions mentioned above, and if it still does not work see Trouble-shooting Altair with Notebook for help.

Once things are up and running, you may wish to go through the tutorials at Basic Statistical Visualization and Exploring Seattle Weather, read through the User Guide indexed in the left panel, or check out the Example Gallery for more ideas.

Quick Start: Altair + Colab

Altair can be used directly in Google’s Colab. Open a notebook, and run the following in a notebook cell:

!pip install altair==2.0.0rc2
import altair as alt
# for colab only run this command once per session
alt.renderers.enable('colab')

Once you have run this, paste the following code to check if renderings are working correctly:

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalLength',
    y='petalWidth',
    color='species'
)

If the plot does not render, ensure you have installed the exact versions mentioned above, and if it still does not work see Display Troubleshooting for help.

Once things are up and running, you may wish to go through the tutorials at Basic Statistical Visualization and Exploring Seattle Weather, read through the User Guide indexed in the left panel, or check out the Example Gallery for more ideas.

Installation with Conda

Conda installation is not available for the version 2.0 release candidate. If you are in a conda environment, you can install altair using pip:

$ conda install pip
$ pip install altair==2.0.0rc2

When the final version 2.0 release is pushed, we will make it available via conda-forge.

Dependencies

Altair has the following dependencies, all of which are installed automatically with the above installation commands:

Development Install

The Altair source repository is available on GitHub. Once you have cloned the repository and installed all the above dependencies, run the following command from the root of the repository to install the master version of Altair:

$ pip install -e .

If you do not wish to clone the source repository, you can install the development version directly from GitHub using:

$ pip install git+https://github.com/altair-viz/altair