{"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":"python","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,"search_vec":"'1.9.0':78 '2026':84 '21':83 'activ':90 'altair':105 'browser':70 'cadenc':94 'chart':22,35,99 'contain':67 'convert':3,7,18,45 'current':75 'data':103 'demonstr':88 'depend':12,73 'dependency-fre':11 'design':16 'develop':91 'emb':50 'equival':33 'extern':69 'format':27 'free':13 'function':38 'imag':31 'includ':28 'januari':82 'javascript':57 'librari':48,58 'lite':21,54,97 'make':63 'node.js':72 'packag':15 'png':30,102 'post1':79 'project':87 'python':4,8,14 'releas':80,93 'rs':46 'runtim':62 'rust':47 'self':66 'self-contain':65 'specif':23,36 'static':26 'svg':29,101 'under':42 'v8':61 'various':25 'vega':20,34,53,56,96,98 'vega-lit':19,52,95 'version':76 'visual':100,104 'vl':2,6,44 'vl-convert-python':1,5 'vl-convert-r':43 'within':59 'without':68 'wrap':40","created_at":"2026-04-12T16:53:47.070019+00:00","updated_at":"2026-04-17T14:02:22.456937+00:00","problems":[{"fix":"Install the package using pip: 'pip install vl-convert-python'.","cause":"The 'vl-convert-python' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'vl_convert'"},{"fix":"Remove the '.py' extension from the import statement: 'import convert'.","cause":"Attempting to import a module with its file extension included.","error":"ImportError: No module named 'convert.py'"},{"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.","cause":"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.","error":"RuntimeError: SVG has an invalid size."},{"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.","cause":"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.","error":"RuntimeError: Failed to convert Vega-Lite spec"},{"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.","cause":"The input Vega-Lite specification is invalid, malformed, or contains elements that the underlying 'vl-convert-rs' Rust backend cannot process.","error":"ValueError: vl_convert_rs returned error: Failed to convert Vega-Lite to SVG: Validation error: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.9.0.post1","cli_name":"vl-convert","cli_version":"sh: 1: vl-convert: not found","type":"library","homepage":null,"github":"https://github.com/jonmmease/vl-convert","docs":null,"changelog":null,"pypi":"https://pypi.org/project/vl-convert-python/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}