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)
  3. Additionally, Altair’s documentation makes use of the vega_datasets package, and so it is included in the installation instructions below.

Depending on the frontend you would like to use, the instructions differ slightly. 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.

Altair works best with JupyterLab version 0.32 or later.

To install JupyterLab and Altair with conda, run the following command:

$ conda install -c conda-forge altair vega_datasets jupyterlab

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

$ pip install -U altair vega_datasets jupyterlab

Once this is finished, run:

$ jupyter lab

In the browser window that launches, select “File”->”New”->”Notebook” and then click “Select” without changing the 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, make certain you have installed the most recent versions of the packages 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 works in the Jupyter notebook, though we recommend using it in JupyterLab if available (see Quick Start: Altair + JupyterLab).

If using the notebook, Altair works best with notebook version 5.3 or newer. Note that using Altair in the notebook also requires the vega_ package to be installed and configured.

To install the notebook and Altair with conda, run the following command:

$ conda install -c conda-forge altair vega_datasets notebook vega

To install the notebook and Altair with pip, run the following command:

$ pip install -U altair vega_datasets notebook vega

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 vega 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 most recent versions of the above packages, 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 with no additional setup by the user. Open a new Colab notebook, and paste the following code to confirm that 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, 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.

Dependencies

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

To run altair’s full test suite and build Altair’s documentation requires a few additional dependencies:

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 .

To install development dependencies as well, run

$ pip install -e .[dev]

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