Pre-release

This release is a pre-release and may not be stable for production use.

Overview

vl-convert-python is a dependency-free Python package for converting Vega-Lite chart specifications into static images (SVG or PNG) or Vega chart specifications.

Since an Altair chart can generate Vega-Lite, this package can be used to easily create static images from Altair charts.

Try it out on Binder!
Binder

Installation

vl-convert-python can be installed using pip with

$ pip install vl-convert-python

Usage

The vl-convert-python package provides a series of conversion functions under the vl_convert module.

Convert Vega-Lite to SVG, PNG, and Vega

The vegalite_to_svg and vegalite_to_png functions can be used to convert Vega-Lite specifications to static SVG and PNG images respectively. The vegalite_to_vega function can be used to convert a Vega-Lite specification to a Vega specification.

import vl_convert as vlc
import json

vl_spec = r"""
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {"url": "https://raw.githubusercontent.com/vega/vega-datasets/next/data/movies.json"},
  "mark": "circle",
  "encoding": {
    "x": {
      "bin": {"maxbins": 10},
      "field": "IMDB Rating"
    },
    "y": {
      "bin": {"maxbins": 10},
      "field": "Rotten Tomatoes Rating"
    },
    "size": {"aggregate": "count"}
  }
}
"""

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)
with open("chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(vl_spec=vl_spec, scale=2)
with open("chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(vl_spec)
with open("chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

Convert Altair Chart to SVG, PNG, and Vega

The Altair visualization library provides a Pythonic API for generating Vega-Lite visualizations. As such, vl-convert-python can be used to convert Altair charts to PNG, SVG, or Vega. The vegalite_* functions support an optional vl_version argument that can be used to specify the particular version of the Vega-Lite JavaScript library to use. Version 4.2 of the Altair package uses Vega-Lite version 4.17, so this is the version that should be specified when converting Altair charts.

import altair as alt
from vega_datasets import data
import vl_convert as vlc
import json

source = data.barley()

chart = alt.Chart(source).mark_bar().encode(
    x='sum(yield)',
    y='variety',
    color='site'
)

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version="4.17")
with open("altair_chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(chart.to_json(), vl_version="4.17", scale=2)
with open("altair_chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(chart.to_json(), vl_version="4.17")
with open("altair_chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

Configure Worker Parallelism

By default, vl-convert-python uses 1 converter worker. You can configure this globally:

import vl_convert as vlc

cfg = vlc.get_config()
print(cfg["num_workers"])  # 1

vlc.configure(num_workers=4)  # enable parallel worker pool
vlc.warm_up_workers()  # optional: pre-initialize workers before first conversion

This setting applies to subsequent conversions and enables parallel work across Python threads.

Google Fonts

Charts that reference Google Fonts can download and register them automatically. There are two approaches:

Explicit Registration

Use register_google_fonts_font to download specific font families before conversion:

import vl_convert as vlc

# Download all variants of Roboto
vlc.register_google_fonts_font("Roboto")

# Download specific weight/style variants
vlc.register_google_fonts_font("Playfair Display", variants=[(400, "normal"), (700, "italic")])

svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)

Automatic Detection

Enable auto_google_fonts to have vl-convert scan the chart specification for font references and download matching Google Fonts automatically:

import vl_convert as vlc

vlc.configure(auto_google_fonts=True)

# Fonts referenced in the spec are downloaded automatically
svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)

Cache Configuration

Downloaded fonts are cached on disk (default ~/.cache/vl-convert/google-fonts/). You can limit the cache size:

vlc.configure(google_fonts_cache_size_mb=500)

Asyncio API

An async API with matching function names is available under vl_convert.asyncio.

import asyncio
import vl_convert.asyncio as vlca

vl_spec = {
    "data": {"values": [{"a": "A", "b": 1}, {"a": "B", "b": 2}]},
    "mark": "bar",
    "encoding": {
        "x": {"field": "a", "type": "nominal"},
        "y": {"field": "b", "type": "quantitative"},
    },
}

async def main():
    await vlca.configure(num_workers=4)
    await vlca.warm_up_workers()  # optional

    svg = await vlca.vegalite_to_svg(vl_spec, "v5_16")
    print(svg[:5])

    svgs = await asyncio.gather(
        *[vlca.vegalite_to_svg(vl_spec, "v5_16") for _ in range(8)]
    )
    print(len(svgs))

asyncio.run(main())

The top-level sync API (vl_convert.<function>) is unchanged. The async namespace is additive.

How it works

This crate uses PyO3 to wrap the vl-convert-rs Rust crate as a Python library. The vl-convert-rs crate is a self-contained Rust library for converting Vega-Lite visualization specifications into various formats. The conversions are performed using the Vega-Lite and Vega JavaScript libraries running in a v8 JavaScript runtime provided by the deno_runtime crate. Font metrics and SVG-to-PNG conversions are provided by the resvg crate.

Of note, vl-convert-python is fully self-contained and has no dependency on an external web browser or Node.js runtime.

Development setup

Create development conda environment

$ conda create -n vl-convert-dev -c conda-forge python=3.10 deno maturin altair pytest black black-jupyter scikit-image

Activate environment and pip install remaining dependencies

$ conda activate vl-convert-dev
$ pip install pypdfium2

Change to Python package directory

$ cd vl-convert-python

Build Rust python package with maturin in develop mode

$ maturin develop --release

Run tests

$ pytest tests

Project links

Data verified by PyPI on Sep 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Stable release available (1.9.0.post1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jmmease from gravatar.com jmmease

GitHub Statistics

Data verified by PyPI on Sep 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD-3-Clause

Requires

Python >=3.9

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vl_convert_python-2.0.0rc3-cp39-abi3-win_amd64.whl (42.2 MB view details)

Uploaded CPython 3.9+Windows x86-64

vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_x86_64.whl (44.5 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ x86-64

vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_aarch64.whl (43.5 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ ARM64

vl_convert_python-2.0.0rc3-cp39-abi3-macosx_11_0_arm64.whl (39.4 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

vl_convert_python-2.0.0rc3-cp39-abi3-macosx_10_12_x86_64.whl (40.6 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file vl_convert_python-2.0.0rc3-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc3-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b3c1ce60df9198fb723e4981e9c0bf2447ecfa206270c6a2e10b37a4842b1b3d
MD5 e739511c5eaf823e998cc8244497221d
BLAKE2b-256 57bdafe61afb1b256c2350bdf83be0a56a3cbd83372d823d3b8210bd302711f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc3-cp39-abi3-win_amd64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a58c04ba47fa9f3028f914919a510671b49e7e8f9a9bf9c3e09dac7aa061dab1
MD5 d18084109d236eaf7e230d82080c9906
BLAKE2b-256 2f011eaa96bb4561daa581a4149e4a3041be21b2eb1a2ea99443781c48241579

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_x86_64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 4ad05911bccd15f462c7e248488f14ad98732b92acbcceea658d836cc4ae23ca
MD5 dd640e79f0ad3156073fb46124d2b406
BLAKE2b-256 da4727d94d93d05ac71052748127d11aabdc205de82df4a310a3f4b0c674eb5c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc3-cp39-abi3-manylinux_2_28_aarch64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc3-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc3-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e4a0616c579ab8c5ef07eef42a14a65d69a4cf350825961814e1954ba19f41ec
MD5 f44cc38e13c427f1129d22f21a603192
BLAKE2b-256 a8e5edbd62d1d2a5633288083405d25187c02dc714bae626ac6983d3400ea4d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc3-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc3-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc3-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 26869d5e0e662e3b2f57b0996d56bc73df1996f2d0603d78e6220c2aa743d543
MD5 8de551306bf24c9b21061a74dedc661a
BLAKE2b-256 716a651d19f53744f9472741b3cb027d2bc854d43bb7f6709f87c48f2bb1fe7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc3-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Pre-release

2.0.0rc5

6 files

This release
Pre-release

2.0.0rc3 This release

5 files

Pre-release

2.0.0rc2

6 files

Pre-release

2.0.0rc1

6 files

1.9.0.post1

6 files

1.9.0

6 files

1.8.0

6 files

1.7.0

6 files

1.6.1

6 files

1.6.0

6 files

1.5.1

5 files

1.5.0

5 files

1.4.0

6 files

1.3.0

6 files

1.2.4

6 files

1.2.3

6 files

1.2.2

6 files

1.2.1

6 files

1.2.0

6 files

1.1.0

6 files

1.0.1

6 files

Pre-release

1.0.1rc1

6 files

1.0.0

6 files

0.14.0

6 files

0.13.1

6 files

0.13.0

6 files

0.12.0

6 files

0.11.2

6 files

0.11.1

26 files

0.11.0

26 files

0.10.3

26 files

0.10.2

26 files

0.10.1

26 files

0.10.0

26 files

0.9.0

26 files

0.8.1

26 files

0.8.0

26 files

0.7.0

25 files

0.6.0

25 files

0.5.0

25 files

0.4.0

25 files

0.3.2

25 files

0.3.1

25 files

0.3.0

25 files

0.2.0

20 files

0.1.0

16 files

0.0.1

16 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page