# Fonts and Google Fonts Vega displays text in charts using fonts. VlConvert loads fonts installed on the host, and to ensure that a suitable fallback font is always available, it bundles [Liberation Sans](https://en.wikipedia.org/wiki/Liberation_fonts). Additionally, you can register fonts located in specific directories, or request fonts from [Google Fonts](https://fonts.google.com/). ## Missing font handling `missing_fonts` decides what happens when a specification's first-choice font is unavailable. `fallback` substitutes silently and is the default, `warn` records a warning, and `error` fails the conversion. ## Make Fonts Available Configure fonts before converting a chart. Pass font directories and Google Font requests as global options. This command uses `chart.vl.json` from the Roboto Slab example in the next section: ```console $ vl-convert \ > --font-dir /opt/app/fonts \ > --google-font 'Inter:400,700italic' \ > --missing-fonts error \ > vl2png --input chart.vl.json --output chart.png ``` `--auto-google-fonts` downloads missing first-choice fonts automatically. ## Render with a Google Font This specification sets `config.font` to Roboto Slab, a family few hosts have installed. Save it as follows: :::{dropdown} chart.vl.json :open: ```{literalinclude} /_examples/google-font.vl.json :language: json ``` ::: Request the family from Google Fonts and render the chart as PNG: ```console $ vl-convert --google-font "Roboto Slab" \ > vl2png --input chart.vl.json --output chart.png --scale 2 ``` VlConvert downloads Roboto Slab on the first conversion, caches it, and lays out and rasterizes the text with it. The PNG output: ```{vl-chart} /_examples/google-font.vl.json :format: png :scale: 2 :google-fonts: Roboto Slab :alt: Bar chart whose title and labels are set in the Roboto Slab typeface ``` Without the request, the text falls back to the default sans-serif font. With `missing_fonts` set to `error`, the conversion fails instead. ## Limit Automatic Downloads `google_font_variant_threshold` limits further font requests once a conversion has resolved that many Google Font variants. Configured, per-conversion, and automatically discovered families all count toward it. At or above the threshold, the next font request fails the conversion. A single request can take the total above the threshold when it resolves several variants. Google Fonts downloads are controlled by these font options only. `allowed_base_urls` governs data and image URLs and has no effect on fonts. ## Google Fonts Cache Downloaded Google Fonts are cached on disk and reused across conversions and process restarts. The cache holds both the Google Fonts CSS responses and the font files. Its directory is the platform cache directory plus `vl-convert/google-fonts`, such as `~/.cache/vl-convert/google-fonts` on Linux or `~/Library/Caches/vl-convert/google-fonts` on macOS. Set the `VLC_GOOGLE_FONTS_CACHE_DIR` environment variable to move it, or set it to `none` to disable caching and download fonts on every conversion. Set the variable before starting VlConvert. Cached font files are evicted least-recently-used once they exceed a 512 MB cap. The cap applies to the whole process and can be changed at runtime. ```console $ vl-convert --google-fonts-cache-size-mb 128 \ > vl2png --input chart.vl.json --output chart.png ``` A value of `0` selects the default cap. ## Embed Fonts in SVG and HTML Set `embed_local_fonts` to include the fonts a chart uses as base64 `@font-face` rules in SVG and HTML output. VlConvert subsets embedded fonts by default so the output contains only the glyphs the chart uses on first render. Set `subset_fonts` to `false` when the text may change later. Passing `bundle` to an SVG conversion also embeds its fonts and images so the file is self-contained. PNG and JPEG contain rendered pixels, and PDF output always embeds the fonts it needs, so consumers of those formats do not need the font files. Embedding increases output size and redistributes the font file, so confirm that the font license permits it. See {doc}`../advanced/font-introspection` to list the fonts VlConvert resolves for a chart.