Altair Change Log

Version 4.2.2 (released Jan 27, 2023)

Bug Fixes

  • Fix incompatibility with jsonschema < 4.5 which got introduced in Altair 4.2.1 (#2860).

Version 4.2.1 (released Jan 26, 2023)

Bug Fixes

  • Disable uri-reference format check in jsonsschema (#2771).

  • Replace iteritems with items due to pandas deprecation (#2683).


  • Add deprecation and removal warnings for Vega-Lite v3 wrappers and Vega v5 wrappers (#2843).

Version 4.2.0 (released Dec 29, 2021)


  • Pie charts are now supported through the use of mark_arc. (Examples: eg. Pie Chart and Radial Chart.)

  • Support for the datum encoding specifications from Vega-Lite; see Vega-Lite Datum Definition. (Examples: Line Chart with datum and Line Chart with datum for color.)

  • angle encoding can now be used to control point styles (Example: Wind Vector Map)

  • Support for serialising pandas nullable data types for float data (#2399).

  • Automatically create an empty data object when Chart is called without a data parameter (#2515).

  • Allow the use of pathlib Paths when saving charts (#2355).

  • Support deepcopy for charts (#2403).

Bug Fixes

  • Fix to_dict() for nested selections (#2120).

  • Fix item access for expressions (#2099).

Version 4.1.0 (released April 1, 2020)

  • Minimum Python version is now 3.6

  • Update Vega-Lite to version 4.8.1; many new features and bug fixes from Vega-Lite versions 4.1 through 4.8; see Vega-Lite Release Notes.


  • strokeDash encoding can now be used to control line styles (Example: Multi Series Line Chart)

  • now relies on altair_saver for more flexibility (#1943).

  • New method replaces chart.serve(), and relies on altair_viewer to allow offline viewing of charts (#1988).

Bug Fixes

  • Support Python 3.8 (#1958)

  • Support multiple views in JupyterLab (#1986)

  • Support numpy types within specifications (#1914)

  • Support pandas nullable ints and string types (#1924)


  • Altair now uses black and flake8 for maintaining code quality & consistency.

Version 4.0.1 (released Jan 14, 2020)

Bug Fixes

  • Update Vega-Lite version to 4.0.2

  • Fix issue with duplicate chart divs in HTML renderer (#1888)

Version 4.0.0 (released Dec 10, 2019)

Version 4.0.0 is based on Vega-Lite version 4.0, which you can read about at

It is the first version of Altair to drop Python 2 compatibility, and is tested on Python 3.5 and newer.


Grammar Changes

  • Sort-by-field can now use the field name directly. So instead of:

    alt.Y('y:Q', sort=alt.EncodingSortField('x', order='descending'))

    you can now use:

    alt.Y('y:Q', sort="-x")
  • The rangeStep argument to Scale and Chart.configure_scale() is deprecated. instead, use{"step": rangeStep}) or chart.configure_view(step=rangeStep).

  • align, center, spacing, and columns are no longer valid chart properties, but are moved to the encoding classes to which they refer.

Version 3.3.0 (released Nov 27, 2019)

Last release to support Python 2


  • Add inheritance structure to low-level schema classes (#1803)

  • Add html renderer which works across frontends (#1793)

  • Support Python 3.8 (#1740, #1781)

  • Add :G shorthand for geojson type (#1714)

  • Add data generator interface: alt.sequence, alt.graticule, alt.sphere() (#1667, #1687)

  • Support geographic data sources via __geo_interface__ (#1664)

Bug Fixes

  • Support pickle and copy.deepcopy for chart objects (#1805)

  • Fix bug when specifying count() within transform_joinaggregate() (#1751)

  • Fix LayerChart.add_selection (#1794)

  • Fix arguments to project() method (#1717)

  • Fix composition of multiple selections (#1707)

Version 3.2.0 (released August 5, 2019)

Upgraded to Vega-Lite version 3.4 (See Vega-Lite 3.4 Release Notes).

Following are changes to Altair in addition to those that came with VL 3.4:


  • Selector values can be used directly in expressions (#1599)

  • Top-level chart repr is now truncated to improve readability of error messages (#1572)

Bug Fixes

  • top-level add_selection methods now delegate to sub-charts. Previously they produced invalid charts (#1607)

  • Unsupported mark_*() methods removed from LayerChart (#1607)

  • New encoding channels are properly parsed (#1597)

  • Data context is propagated when encodings are specified as lists (#1587)

Backward-Incompatible Changes

  • alt.LayerChart no longer has mark_*() methods, because they never produced valid chart specifications) (#1607)

Version 3.1.0 (Released June 6, 2019)

Update includes full compatibility with version 3.3 of Vega-Lite.


  • Added support for vega themes via alt.themes.enable(theme_name) (#1539)

  • Added an alt.renderers.disable_max_rows() method for disabling the maximum rows check (#1538)

  • Improved user-facing warnings/errors around layering and faceting (#1535).

  • data argument is now properly handled by (#1525)

  • Compound charts (layer, concat, hconcat, vconcat) now move data to the top level by default. In particular, this means that the facet() method can now be called directly on a layered chart without having to change how data is specified. (#1521)

  • alt.LayerChart now supports mark_*() methods. If a layer specifies a mark at the top level, all child charts will inherit it (unless they override it explicitly).

  • alt.Chart.facet() now handles wrapped facets; for example: python   chart.facet('column_name', columns=5) See altair/examples/ for a more complete example.

Bug fixes

  • Make chart.serve() and respect the data transformer setting (#1538)

  • Fixed a deserialization bug for certain chart specs in schemapi (#1543)

Backward-Incompatible Changes

  • alt.Chart.facet() now accepts a wrapped facet encoding as a first positional argument, rather than a row encoding. The following are examples of old invocations, and the equivalent new invocations:

  • chart.facet(row='col1', column='col2'): unchanged

  • chart.facet('col1', 'col2'): change to chart.facet(row='col1', column='col2')

  • chart.facet('col1'): change to chart.facet(row='col1')

In each case, the new invocations are compatible back to Altair 2.X.

  • Several of the encoding channels added in 3.0 have had their capitalization corrected to better match the names used in the schema:

  • alt.Fillopacity -> alt.FillOpacity

  • alt.Strokeopacity -> alt.StrokeOpacity

  • alt.Strokewidth -> alt.StrokeWidth

  • alt.Xerror -> alt.XError

  • alt.Xerror2 -> alt.XError2

  • alt.Yerror -> alt.YError

  • alt.Yerror2 -> alt.YError2

Version 3.0.1 (Released May 1, 2019)

Fix version info bug for HTML output and Colab & Kaggle renderers.

Version 3.0.0 (Released April 26, 2019)

Update to Vega-Lite 3.2 and Vega 5.3 & support all new features. See for Vega-Lite feature lists.


  • new compound marks: mark_boxplot(), mark_errorband(), mark_errorbar()

  • new transforms: transform_impute(), transform_joinaggregate(), transform_flatten() transform_fold(), transform_sample(), transform_stack()

  • new facet encoding that is similar to the row and column encoding, but allows for wrapped facets

  • new alt.concat() function that is similar to alt.hconcat and alt.vconcat, but allows for more general wrapped concatenation

  • new columns keyword that allows wrapped faceting, repeating, and concatenation.

  • many, many bug fixes

  • tooltips can now be automatically populated using the tooltip mark configuration.

  • ability to specify initial conditions for selections

Version 2.4.1 (Released February 21, 2019)


  • Several documentation cleanups & new examples

Bug Fixes

  • Fix incompatibility with pandas version 0.24 (#1315)

Version 2.3.0 (Released December 7, 2018)

Includes many reworked examples in the example gallery.


  • Better errors for non-string column names, as well as automatic conversion of pandas.RangeIndex columns to strings (#1107)

  • Renderers now have set_embed_options() method (#1203)

  • Added kaggle renderer & more HTML output options (#1123)

Backward-incompatible changes


  • fix typing requirement in Python 3.6+ (#1185)

  • Added support & CI testing for Python 3.7 (#1008)

Bug fixes

  • Selection predicates now recognize all valid entries (#1143)

  • Python 2 support for (#1134)

Version 2.2.2 (Released August 17, 2018)

Bug Fixes

  • fix missing JSON resource in altair.vega.v4 (#1097)

Version 2.2.1 (Released August 15, 2018)

Bug Fixes

  • appropriate handling of InlineData in dataset consolidation (#1092)

  • fix admonition formatting in documentation page (#1094)

Version 2.2.0 (Released August 14, 2018):


  • better handling of datetimes and timezones (#1053)

  • all inline datasets are now converted to named datasets and stored at the top level of the chart. This behavior can be disabled by setting alt.data_transformers.consolidate_datasets = False (#951 & #1046)

  • more streamlined shorthand syntax for window transforms (#957)


Backward-incompatible changes

  • alt.SortField renamed to alt.EncodingSortField and alt.WindowSortField renamed to alt.SortField (#3741)

Bug Fixes

  • Fixed serialization of logical operands on selections within transform_filter(): (#1075)

  • Fixed sphinx issue which embedded chart specs twice (#1088)

  • Avoid Selenium import until it is actually needed (#982)

Version 2.1.0 (Released June 6, 2018):


  • add a scale_factor argument to to allow the size/resolution of saved figures to be adjusted. (#918)

  • add an add_selection() method to add selections to charts (#832)

  • add chart.serve() and chart.display() methods for more flexibility in displaying charts (#831)

  • allow multiple fields to be passed to encodings such as tooltip and detail (#830)

  • make timeUnit specifications more succinct, by parsing them in a manner similar to aggregates (#866)

  • make to_json() and to_csv() have deterministic filenames, so in json mode a single datasets will lead to a single on-disk serialization (#862)

Breaking Changes

  • make data the first argument for all compound chart types to match the semantics of alt.Chart (this includes alt.FacetChart, alt.LayerChart, alt.RepeatChart, alt.VConcatChart, and alt.HConcatChart) (#895).

  • update vega-lite to version 2.4.3 (#836)

  • Only API change is internal: alt.MarkProperties is now alt.MarkConfig


  • update vega to v3.3 & vega-embed to v3.11 in html output & colab renderer (#838)

Version 2.0.0: May 2, 2018

  • Complete rewrite of Altair, focused on supporting Vega-Lite 2.X

Version 1.2.1: October 29, 2017

This version of Altair is based on Vega-Lite 1.2.1.

Major additions

  • Support for JupyterLab/nteract through MIME based rendering. Enable this by calling enable_mime_rendering() before rendering visualizations (#216).

  • Change default import in all code and docs to import altair as alt

  • Check for missing and misspelled column names upon exporting or rendering, and raise FieldError (#399) if any problems are found. This can be disabled by setting Chart.validated_columns=False.

  • Raise MaxRowsExceeded if the number of rows in the dataset is larger than Chart.max_rows to guard against sending large datasets to the browser.

  • Move the Vega-Lite 1.x api into altair.v1 to make it easier for us to migrate to Vega-Lite 2.x and continue to support 1.x. No import change are needed as altair.v1 is aliased to altair in this releasealtair.v1 (#377).

  • Moved the example notebooks into a separate repository ( that has Binder support (#391).

  • Add $schema to top-level JSON spec (#370).

  • Minor documentation revisions.

Bug fixes

  • Make sure default mark is a point (#344).

Version 1.2: Nov 7, 2016

Major additions

Bug fixes

  • Countless minor bug fixes


  • Update to Vega-Lite 1.2.1 and add its supported features

  • Create website:

  • Set up Travis to run conda & pip; and to build documentation

Version 1.0: July 11, 2016

  • Initial release of Altair