vl-convert-python

1.9.0.post1 · active · verified Sun Apr 12

vl-convert-python is a dependency-free Python package designed for converting Vega-Lite chart specifications into various static formats, including SVG, PNG images, or equivalent Vega chart specifications. It functions by wrapping the underlying `vl-convert-rs` Rust library, which embeds the Vega-Lite and Vega JavaScript libraries within a v8 runtime, making it self-contained without external browser or Node.js dependencies. The current version is 1.9.0.post1, released on January 21, 2026, and the project demonstrates an active development and release cadence.

Warnings

gotcha Text rendering in generated images requires fonts referenced by the chart to be installed on the system where vl-convert-python is running. In environments like Google Colab, default fonts may be limited. Custom font directories can be registered using `vl_convert.register_font_directory()`.
Fix: Ensure necessary fonts are installed on the system or register custom font directories using `vl_convert.register_font_directory('/path/to/fonts')`.
gotcha It is crucial to explicitly specify the `vl_version` parameter when calling conversion functions (e.g., `vegalite_to_svg`, `vegalite_to_png`). If converting charts generated by libraries like Altair, ensure the `vl_version` matches the Vega-Lite version supported by that Altair version (e.g., Altair 4.2 uses Vega-Lite 4.17).
Fix: Always pass the `vl_version` argument, e.g., `vlc.vegalite_to_svg(vl_spec=my_spec, vl_version="5.json")` or `vlc.vegalite_to_svg(chart.to_json(), vl_version="4.17")` for Altair charts.
gotcha When integrating with VegaFusion, `vl-convert-python` is often a required dependency. Users have encountered `ModuleNotFoundError` if `vl-convert-python` is not installed correctly alongside VegaFusion.
Fix: Ensure `vl-convert-python` is installed, ideally as part of `vegafusion`'s extra dependencies: `pip install -U "vegafusion[embed]"` or separately with `pip install -U vl-convert-python`.

Install

pip install vl-convert-python Install latest version

Imports

vl_convert
```
import vl_convert as vlc
```
While a VlConverter class exists, modern usage typically directly imports the `vl_convert` module and calls functions like `vlc.vegalite_to_svg` or `vlc.vegalite_to_png`.

Quickstart

This quickstart demonstrates converting a simple Vega-Lite chart specification, provided as a JSON string, into an SVG string and PNG bytes using the `vegalite_to_svg` and `vegalite_to_png` functions. It also highlights the importance of specifying the Vega-Lite version and shows an example of how one might integrate with Altair charts.

import vl_convert as vlc
import json

# A simple Vega-Lite chart specification as a Python dictionary
vl_spec = {
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "description": "A simple bar chart with embedded data.",
    "data": {"values": [{"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43}]},
    "mark": "bar",
    "encoding": {
        "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
        "y": {"field": "b", "type": "quantitative"}
    }
}

# Convert to SVG string
# It's crucial to pass the spec as a JSON string and specify vl_version
svg_str = vlc.vegalite_to_svg(vl_spec=json.dumps(vl_spec), vl_version="5.json")

# Convert to PNG bytes with a scale factor
png_data = vlc.vegalite_to_png(vl_spec=json.dumps(vl_spec), scale=2, vl_version="5.json")

print(f"Generated SVG (first 100 chars): {svg_str[:100]}...")
print(f"Generated PNG data (first 10 bytes): {png_data[:10]}...")

# To save to files (uncomment to enable):
# with open("output_chart.svg", "wt") as f:
#     f.write(svg_str)
# with open("output_chart.png", "wb") as f:
#     f.write(png_data)

# Example for Altair charts (requires altair installed):
# import altair as alt
# from vega_datasets import data
# chart = alt.Chart(data.cars.url).mark_point().encode(
#     x='Horsepower:Q',
#     y='Miles_per_Gallon:Q'
# )
# # Use the vl_version compatible with your Altair version (e.g., Altair 4.2 uses VL 4.17)
# altair_svg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version="4.17")
# print(f"Generated Altair SVG length: {len(altair_svg_str)} bytes")

view raw JSON →