Upgrading from 1.x#
Version 2 keeps the conversions you already use but changes some details on how converters are configured, tightens data access, and replaces a few options. This page lists what to change when moving from 1.9 to 2.0, followed by behavior differences to check even when your code still runs.
Update Your Commands#
Removed and renamed options. Commands that pass these fail with unexpected argument:
1.x |
2.0 |
|---|---|
|
Removed. Warnings print to standard error by default. Adjust with the global |
|
Global |
|
Removed with |
The default chart config file is no longer applied. 1.x used ~/.config/vl-convert/config.json as the Vega-Lite config for every command when that file existed. 2.0 ignores it, and --config has no default. To keep a default chart configuration, put it in a converter config file as a custom theme and select it with default_theme. Save this example at the path printed by vl-convert config-path:
vlc-config.jsonc
{
"themes": {"house": {"axis": {"labelFont": "Inter", "titleFont": "Inter"}}},
"default_theme": "house"
}
The file loads automatically from that path. You can instead pass the converter configuration with --vlc-config. Alternatively, keep the 1.x chart configuration as a separate file and pass its path with --config on each chart conversion. See Configuration.
The default Vega-Lite version is 6.4. 1.x commands defaulted to 5.21. Pass --vl-version 5.21 to keep the old output for specifications that depend on Vega-Lite 5 behavior.
Input and output are optional. --input and --output now default to standard input and standard output, and vl2url and vg2url gained --output. Commands that pass both options work unchanged. See Standard Input and Output.
New commands and options. vl2fonts, vg2fonts, vl2sg, vg2sg, bundle-js, config-path, and serve are new. --font-dir is now global and repeatable, and new global options cover the converter config file, data access, logging, Google Fonts, plugins, and JavaScript limits. Each has a VLC_* environment variable. Run vl-convert --help for the list.
Check Behavior Differences#
These differences can change results even when code and commands still run.
The allowlist now covers images as well as data. HTTP and HTTPS URLs remain allowed by default. Custom allowed_base_urls settings now restrict image loading too, so include any image locations your charts use. Local data and image files remain blocked unless the allowlist permits them.
The default base URL has changed. The default base_url, that relative URLs resolve against, is now https://cdn.jsdelivr.net/npm/vega-datasets@v3.2.1/ instead of https://vega.github.io/vega-datasets/. If your allowlist only permits the old host, update it or set base_url to the old location. See Loading Data and Images.
Absolute data and image paths refer to local files. Paths such as /data/cars.csv and, on Windows, C:\data\cars.csv no longer resolve against base_url. Allow the directory to load them without a file:// prefix. For a remote resource, remove the leading slash to resolve data/cars.csv against base_url, or use an explicit HTTP or HTTPS URL. Chart hyperlinks keep their existing URL behavior.
Warnings are always captured. 1.x dropped Vega and Vega-Lite warnings unless you asked for them. 2.0 records them on every conversion and reports them through each interface’s logging, so expect to see messages you did not see before. They are worth reading! A warning often explains why a chart renders differently than expected. See Logging and Warnings.
PNG pixels may differ slightly. To build a PNG image, 1.x first generated an SVG and then rasterized the SVG using the resvg crate. This approach generally worked well, but one limitation was that it did not support Vega’s label transform. Also, the SVG generation followed by SVG parsing had some overhead for charts with many mark instances.
Version 2.0 renders PNGs using Vega’s canvas renderer with a new Canvas 2D implementation based on tinyskia and cosmic-text. This may result in small pixel-level changes to PNGs. Regenerate image baselines in tests that compare PNG bytes.