Display Troubleshooting¶

Altair has a number of moving parts: it creates data structures in Python, those structures are passed to front-end renderers, and the renderers run JavaScript code to generate the output. This complexity means that it’s possible to get into strange states where things don’t immediately work as expected.

This section summarizes some of the most common problems and their solutions.

Trouble-shooting Altair with JupyterLab¶

JupyterLab: VegaLite 2 Object¶

If you are using the Jupyter notebook rather than JupyterLab, then refer to Notebook: VegaLite 2 object

If you are using JupyterLab (not Jupyter notebook) and see the following output:

<VegaLite 2 object>

This most likely means that you are using too old a version of JupyterLab. Altair works best with JupyterLab version 0.32 or later; check the version with:

$ jupyter lab --version
0.32.1

If this is the problem, then use pip install -U jupyterlab or conda update jupyterlab to update JupyterLab, depending on how you first installed it.

JavaScript output is disabled in JupyterLab¶

If you are using JupyterLab and see the following ouput:

JavaScript output is disabled in JupyterLab

it can mean one of two things is wrong

You are using an old version of Altair. JupyterLab only works with Altair version 2.0 or newer; you can check the altair version by executing the following in a notebook code cell:
```
import altair as alt
alt.__version__
```
If the version is older than 2.0, then exit JupyterLab and follow the installation instructions at Quick Start: Altair + JupyterLab.
You have enabled the wrong renderer. JupyterLab works with the default renderer, but if you have used alt.renderers.enable() to enable another renderer, charts will no longer render correctly in JupyterLab. You can check which renderer is active by running:
```
import altair as alt
print(alt.renderers.active)
```
JupyterLab rendering will work only if the active renderer is "default" or "jupyterlab". You can re-enable the default renderer by running:
```
import altair as alt
alt.renderers.enable('default')
```
(Note that the default renderer is enabled, well, by default, and so this is only necessary if you’ve somewhere changed the renderer explicitly).

JupyterLab: Textual Chart Representation¶

If you are using the Notebook rather than the JupyterLab, then refer to Notebook: Textual Chart Representation

If you are using JupyterLab and see a textual representation of the Chart object similar to this:

Chart({
  data: 'https://vega.github.io/vega-datasets/data/cars.json',
  encoding: EncodingWithFacet({
    x: X({
      shorthand: 'Horsepower'
    })
  }),
  mark: 'point'
})

it probably means that you are using an older Jupyter kernel. You can confirm this by running:

import IPython; IPython.__version__
# 6.2.1

Altair will not display correctly if using a kernel with IPython version 4.X or older.

The easiest way to address this is to change your kernel: choose “Kernel”->”Change Kernel” and then use the first kernel that appears.

Trouble-shooting Altair with Notebook¶

Notebook: VegaLite 2 object¶

If you are using JupyterLab rather than the Jupyter notebook, then refer to JupyterLab: VegaLite 2 Object

If you are using the notebook (not JupyterLab) and see the the following output:

<Vegalite 2 object>

it means that either:

You have forgotten to enable the notebook renderer. As mentioned in Quick Start: Altair + Notebook, you need to install the vega package and Jupyter extension, and then enable it using:
```
import altair as alt
alt.renderers.enable('notebook')
```
in order to render charts in the classic notebook.

If the above code gives an error:
```
NoSuchEntryPoint: No 'notebook' entry point found in group 'altair.vegalite.v2.renderer'
```
This means that you have not installed the vega package. If you see this error, please make sure to follow the standard installation instructions at Quick Start: Altair + Notebook.
Have too old a version of Jupyter notebook. Run:
```
$ jupyter notebook --version
```
and make certain you have version 5.3 or newer. If not, then update the notebook using either pip install -U jupyter notebook or conda update jupyter notebook depending on how you first installed the packages.

If you have done the above steps and charts still do not render, it likely means that you are using a different Kernel within your notebook. Switch to the kernel named Python 2 if you are using Python 2, or Python 3 if you are using Python 3.

Notebook: Textual Chart Representation¶

If you are using the Notebook rather than the JupyterLab, then refer to JupyterLab: Textual Chart Representation

If you are using Jupyter notebook and see a textual representation of the Chart object similar to this:

Chart({
  data: 'https://vega.github.io/vega-datasets/data/cars.json',
  encoding: EncodingWithFacet({
    x: X({
      shorthand: 'Horsepower'
    })
  }),
  mark: 'point'
})

it probably means that you are using an older Jupyter kernel. You can confirm this by running:

import IPython; IPython.__version__
# 6.2.1

Altair will not display correctly if using a kernel with IPython version 4.X or older.

The easiest way to address this is to change your kernel: choose “Kernel”->”Change Kernel” and then select “Python 2” or “Python 3”, depending on what version of Python you used when installing Altair.

General Trouble-shooting¶

Plot displays, but the content is empty¶

Sometimes you end up with an empty plot; for example:

import altair as alt

alt.Chart('nonexistent_file.csv').mark_line().encode(
    x='x:Q',
    y='y:Q',
)

In this case, the plot was empty because the data, 'nonexistent_file.csv', does not exist, or contains a typo in the URL.

A similar blank chart results if you refer to a field that does not exist in the data; for example:

import pandas as pd

data = pd.DataFrame({'x': [1, 2, 3],
                     'y': [3, 1, 4]})

alt.Chart(data).mark_point().encode(
    x='x:Q',
    y='y:Q',
    color='color:Q'  # <-- this field does not exist in the data!
)

Altair does not check whether fields are valid, because there are many avenues by which a field can be specified within the full schema, and it is too difficult to account for all corner cases. Improving the user experience in this is a priority; see https://github.com/vega/vega-lite/issues/3576.

Chart does not display at all¶

For all renderers, the chart is only displayed if the last line of the cell evaluates to a chart object

By analogy, consider the output of simple Python operations:

>>> x = 4  # no output here
>>> x      # output here, because x is evaluated
4
>>> x * 2  # output here, because the expression is evaluated
8

If the last thing you type consists of an assignment operation, there will be no output displayed. This turns out to be true of Altair charts as well:

import altair as alt
from vega_datasets import data
cars = data.cars.url

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

The last statement is an assignment, so there is no output and the chart is not shown. If you have a chart assigned to a variable, you need to end the cell with an evaluation of that variable:

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

chart

Alternatively, you can evaluate a chart directly, and not assign it to a variable, in which case the object definition itself is the final statement and will be displayed as an output:

alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N',
)