This release is a pre-release and may not be stable for production use.
vl-convert-python
vl-convert-python converts Vega-Lite, Vega, and SVG input from Python. For
Vega and Vega-Lite charts, it produces SVG, PNG, JPEG, PDF, HTML, scenegraphs,
font metadata, and Vega Editor URLs. It also compiles Vega-Lite to Vega and
converts existing SVG to PNG, JPEG, or PDF.
The package embeds the official Vega and Vega-Lite JavaScript libraries. It does not require a browser, Node.js, or a separate rendering service.
Installation
Add the package to a project with uv:
uv add "vl-convert-python>=2.0.0rc1,<3"
Python 3.10 and later are supported.
Vega-Lite Example
Conversion functions accept a JSON-compatible dictionary or a JSON string:
import vl_convert as vlc
spec = {
"data": {
"values": [
{"category": "A", "value": 3},
{"category": "B", "value": 7},
]
},
"mark": "bar",
"encoding": {
"x": {"field": "category", "type": "nominal"},
"y": {"field": "value", "type": "quantitative"},
},
}
svg = vlc.vegalite_to_svg(spec)
with open("chart.svg", "w", encoding="utf-8") as output_file:
output_file.write(svg)
png = vlc.vegalite_to_png(spec, scale=2)
with open("chart.png", "wb") as output_file:
output_file.write(png)
Use vegalite_to_vega() to inspect or save the compiled Vega specification:
import json
vega_spec = vlc.vegalite_to_vega(spec)
with open("chart.vg.json", "w", encoding="utf-8") as output_file:
json.dump(vega_spec, output_file)
Altair Example
Pass the result of Chart.to_dict() directly to a Vega-Lite conversion:
import altair as alt
import vl_convert as vlc
chart = (
alt.Chart(alt.Data(values=[{"x": "A", "y": 3}, {"x": "B", "y": 7}]))
.mark_bar()
.encode(x="x:N", y="y:Q")
)
png = vlc.vegalite_to_png(chart.to_dict(), scale=2)
Select a bundled Vega-Lite compiler when a chart depends on an older release:
svg = vlc.vegalite_to_svg(spec, vl_version="5.16")
Configuration
configure() sets process-wide defaults. Conversion arguments override these
defaults for one call where the API provides a matching argument.
import vl_convert as vlc
vlc.configure(
num_workers=4,
base_url=False,
allowed_base_urls=["https://data.example.com/"],
max_v8_heap_size_mb=512,
max_v8_execution_time_secs=10,
)
Use load_config() to read the shared JSONC configuration format. Use
get_config() to inspect the active configuration.
Fonts
VlConvert uses installed system fonts and accepts additional font directories.
Google Fonts downloads are opt-in. This example uses spec from the first
example:
import vl_convert as vlc
vlc.configure(auto_google_fonts=True)
svg = vlc.vegalite_to_svg(spec)
Use vegalite_fonts() or vega_fonts() to inspect the fonts that VlConvert
resolves. These functions list local fonts only when embed_local_fonts is
enabled and list Google Fonts only when they are requested or automatic Google
Fonts are enabled.
Asyncio
Awaitable conversion functions are available under vl_convert.asyncio. This
example uses spec from the first example:
import asyncio
import vl_convert.asyncio as vlca
async def main():
svg = await vlca.vegalite_to_svg(spec)
print(svg[:5])
asyncio.run(main())
Most functions in the asyncio namespace are awaitable, including conversion,
configuration, worker, font-registration, theme, locale, and bundle helpers.
Only these process-global lookups and setters are synchronous re-exports:
current_font_directories(), google_fonts_cache_dir(),
google_fonts_cache_size_mb(), set_google_fonts_cache_size_mb(),
get_format_locale(), get_time_format_locale(), get_vega_version(),
get_vega_themes_version(), get_vega_embed_version(),
get_vegalite_versions(), and get_config_path(). Do not await those
functions.
Network and File Access
The bundled JavaScript libraries need no network access. Specifications can
still request remote data and images, and optional Google Fonts or plugins can
make additional requests. Data and images share the allowed_base_urls
policy. Local files are blocked by default.
See the repository's documentation source for the complete configuration and API guides.
Development
From the repository root, build the extension in the Pixi environment and run its tests:
pixi run dev-py
pixi run test-py
pixi run fmt-py-check
1 maintainer
Release files for vl-convert-python 2.0.0rc7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vl_convert_python-2.0.0rc7.tar.gz | 6.1 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| vl_convert_python-2.0.0rc7-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| vl_convert_python-2.0.0rc7-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| vl_convert_python-2.0.0rc7-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 225.5 MB
Release files / vl_convert_python-2.0.0rc7.tar.gz
| Download URL | vl_convert_python-2.0.0rc7.tar.gz |
|---|---|
| Size | 6.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a9f6ee40370ec48cbf5190f36101e13e03a0d177ceb822054dd2ca4f67fadb4
|
|
BLAKE2b-256 checksum How to use checksums |
88ff9714412a34f60a3ad1162099633b1ec78d106c4cc34276df71340b03d104
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / vl_convert_python-2.0.0rc7-cp310-abi3-win_amd64.whl
| Download URL | vl_convert_python-2.0.0rc7-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 43.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3c8f9e1e960ffd65d378669c8b18ee21fdaebc04e12aed31eb555a0bb8b6b243
|
|
BLAKE2b-256 checksum How to use checksums |
f9b5c088025b5efc663fe1fba1af0e5363aa01145fe9837c47478bc0179e3b00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 46.3 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
4a5306fd9ccb0b94ed0aa621647c2f7c199ddb80c5b06ef910da4fbb70b38190
|
|
BLAKE2b-256 checksum How to use checksums |
0a4d930d22bc61e4e3adbe1b02cc84a301dc1c8f49b86eec48d8224dfab431bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | vl_convert_python-2.0.0rc7-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 46.2 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e317b03a37755ef882b55e7936f7e360804690c0cb2ae1045619c3944334f3dd
|
|
BLAKE2b-256 checksum How to use checksums |
f53d414d6acc9eadabe9aa672de6296240f08b4925ed2ffaf5589114569c5756
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / vl_convert_python-2.0.0rc7-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | vl_convert_python-2.0.0rc7-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 41.2 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
400535cc9172995cf1152847a2ac24c93657ba8b00345daac61c76260fbdc561
|
|
BLAKE2b-256 checksum How to use checksums |
b50e6d8acc539b8486b8789732a545738f8e446bf778cdabfb8a9d5763bc128b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / vl_convert_python-2.0.0rc7-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | vl_convert_python-2.0.0rc7-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 41.9 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
59e79d60a06bdf7b5c3720d91e5f751e347ee5419877523d3576cfde453f8e7a
|
|
BLAKE2b-256 checksum How to use checksums |
1a38c14a182268889b138fb735c59187feb92ab0362638dae254bd0a33c14960
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
