{"id":5093,"library":"vl-convert-python","title":"vl-convert-python","description":"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.","status":"active","version":"1.9.0.post1","language":"en","source_language":"en","source_url":"https://github.com/jonmmease/vl-convert","tags":["vega-lite","vega","charting","visualization","svg","png","data visualization","altair"],"install":[{"cmd":"pip install vl-convert-python","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"from vl_convert import VlConverter # Generally not needed for direct conversion functions","symbol":"vl_convert","correct":"import vl_convert as vlc"}],"quickstart":{"code":"import vl_convert as vlc\nimport json\n\n# A simple Vega-Lite chart specification as a Python dictionary\nvl_spec = {\n    \"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\",\n    \"description\": \"A simple bar chart with embedded data.\",\n    \"data\": {\"values\": [{\"a\": \"A\", \"b\": 28}, {\"a\": \"B\", \"b\": 55}, {\"a\": \"C\", \"b\": 43}]},\n    \"mark\": \"bar\",\n    \"encoding\": {\n        \"x\": {\"field\": \"a\", \"type\": \"nominal\", \"axis\": {\"labelAngle\": 0}},\n        \"y\": {\"field\": \"b\", \"type\": \"quantitative\"}\n    }\n}\n\n# Convert to SVG string\n# It's crucial to pass the spec as a JSON string and specify vl_version\nsvg_str = vlc.vegalite_to_svg(vl_spec=json.dumps(vl_spec), vl_version=\"5.json\")\n\n# Convert to PNG bytes with a scale factor\npng_data = vlc.vegalite_to_png(vl_spec=json.dumps(vl_spec), scale=2, vl_version=\"5.json\")\n\nprint(f\"Generated SVG (first 100 chars): {svg_str[:100]}...\")\nprint(f\"Generated PNG data (first 10 bytes): {png_data[:10]}...\")\n\n# To save to files (uncomment to enable):\n# with open(\"output_chart.svg\", \"wt\") as f:\n#     f.write(svg_str)\n# with open(\"output_chart.png\", \"wb\") as f:\n#     f.write(png_data)\n\n# Example for Altair charts (requires altair installed):\n# import altair as alt\n# from vega_datasets import data\n# chart = alt.Chart(data.cars.url).mark_point().encode(\n#     x='Horsepower:Q',\n#     y='Miles_per_Gallon:Q'\n# )\n# # Use the vl_version compatible with your Altair version (e.g., Altair 4.2 uses VL 4.17)\n# altair_svg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version=\"4.17\")\n# print(f\"Generated Altair SVG length: {len(altair_svg_str)} bytes\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure necessary fonts are installed on the system or register custom font directories using `vl_convert.register_font_directory('/path/to/fonts')`.","message":"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()`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions when used with VegaFusion"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}