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
muslpy 3.10–3.95 runs
build_error
glibcpy 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()`.fixEnsure 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).fixAlways 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.fixEnsure `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.
fixInstall 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.
fixRemove 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.
fixReview 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.
fixCarefully 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.
fixEnsure 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.