Registry / data / vl-convert-python

vl-convert-python

JSON →
library1.9.0.post1pypypi✓ verified 26d ago

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.

pip install vl-convert-python
INSTALL
IMPORT
SIG · VL-CONVERT-PYTHON
V
vl-convert-python
datapythonv1.9.0.post1
Install
2.9s avg
Import
10ms
Disk
100MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.9.0.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
build_error
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.002s · 102MB
100MB installed
● package 100MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

vl_convert
✓ import vl_convert as vlc
✗ from vl_convert import VlConverter # Generally not needed for direct conversion functions
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`.

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")
vl-convert --version
Debug
Known issues
gotchaText 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')`.
affects: All versions
gotchaIt 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.
affects: All versions
gotchaWhen 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`.
affects: All versions when used with VegaFusion
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vl_convert'
The 'vl-convert-python' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install vl-convert-python'.
ImportError: No module named 'convert.py'
Attempting to import a module with its file extension included.
fix
Remove the '.py' extension from the import statement: 'import convert'.
RuntimeError: SVG has an invalid size.
The provided Vega-Lite specification results in an SVG output that is considered invalid or has an unresolvable size, often due to issues within the specification itself, such as incorrect data binding or rendering logic.
fix
Review your Vega-Lite specification for errors, ensure all required data fields are present and correctly formatted, and check for proper sizing and layout definitions. Test the spec in the Vega Editor to isolate issues.
RuntimeError: Failed to convert Vega-Lite spec
An unspecific error occurred during the conversion process from Vega-Lite to the target format (SVG, PNG, or Vega), often due to an invalid or malformed Vega-Lite specification, or an issue with the underlying JavaScript runtime processing the spec.
fix
Carefully review the Vega-Lite specification for any syntax errors, missing properties, or invalid data. Test the specification in an online Vega-Lite editor (e.g., Vega Editor) to validate its correctness and pinpoint specific issues.
ValueError: vl_convert_rs returned error: Failed to convert Vega-Lite to SVG: Validation error: ...
The input Vega-Lite specification is invalid, malformed, or contains elements that the underlying 'vl-convert-rs' Rust backend cannot process.
fix
Ensure the Vega-Lite JSON is valid and adheres to the Vega-Lite schema. Debug the spec using online validators or by simplifying it to identify the problematic part, then retry the conversion.
Upgrade
Version history
1.9.0.post1latest on PyPI · released Jan 21, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
52 hits · last 30 days
node
48
OpenAI (training)
1
Resources
vl-convert-python — pip install vl-convert-python · libregistry