Scripting SVG Exports with the Inkscape CLI: Reproducible PNG and PDF Output Without the GUI

The short version

If you need to convert SVGs to PNG or PDF in a build pipeline, CI job, or batch script, Inkscape does it headlessly. Since Inkscape 1.0 the command line uses explicit verbs and long options, so a typical export looks like this:

inkscape icon.svg --export-type=png \
  --export-filename=icon-256.png \
  --export-width=256 --export-height=256

Run it from any shell on a machine with Inkscape installed; no display is required for pure export tasks, and no special permissions are needed beyond read access to the input and write access to the output directory. The two things that most often bite people are the old pre-1.0 flag syntax (which no longer works) and the default export area (the page, not your artwork). Both are covered below.

Check your version first

The CLI changed substantially between Inkscape 0.92.x and 1.0. Scripts written for the old releases use flags like -e (export PNG) and -z (no GUI). On a modern build those flags either error out or behave unexpectedly, and the failure mode in a CI log is not always obvious.

Before writing or debugging a script, confirm what you have:

inkscape --version
inkscape --help

The examples in this article assume Inkscape 1.0 or later. If --version reports 0.92.x, either upgrade or look up the legacy syntax for that release — do not mix the two.

A worked example: reproducible raster export

Say you have an app icon, icon.svg, and your build needs a deterministic 256×256 PNG. The full command:

inkscape icon.svg \
  --export-type=png \
  --export-filename=icon-256.png \
  --export-width=256 \
  --export-height=256 \
  --export-overwrite

What each piece does:

• --export-type=png selects the output format. pdf and svg (for plain/optimized SVG) are also common.
• --export-filename sets the output path. Without it, Inkscape derives a name from the input, which is fine interactively but fragile in scripts.
• --export-width and --export-height force the pixel dimensions. Set both explicitly — see the DPI pitfall below.
• --export-overwrite replaces an existing output file without prompting. In a non-interactive script a prompt would hang the job, so include it deliberately.

To verify the result is reproducible, run the command twice into different filenames and compare:

inkscape icon.svg --export-type=png --export-filename=a.png \
  --export-width=256 --export-height=256
inkscape icon.svg --export-type=png --export-filename=b.png \
  --export-width=256 --export-height=256
sha256sum a.png b.png

Identical hashes confirm your settings fully determine the output. (Minor PNG differences can legitimately appear across Inkscape versions or builds, so compare hashes only within the same environment.)

Export area: the default surprises people

By default, Inkscape exports the page region. If your artwork extends beyond the page frame — common when icons are drawn on an oversized canvas — the exported PNG includes empty page space and your subject appears small or off-center.

Two options control this:

For asset pipelines, --export-area-drawing is usually what you want: the output hugs the artwork regardless of page setup. Decide per asset type and put the choice in the script, not in someone's memory.

Exporting a single element

For sprite sheets or multi-icon files you can export one object by its XML ID:

inkscape sprites.svg --export-id=icon-settings \
  --export-type=png --export-filename=icon-settings.png \
  --export-width=64 --export-height=64

The ID is the object's id attribute in the SVG source (visible in Inkscape's Object Properties panel). Only that element and its bounding box are exported. This is a clean way to keep one master SVG and extract individual assets at build time.

Batch conversion

Inkscape accepts multiple input files in one invocation and applies the same export options to each:

inkscape a.svg b.svg c.svg --export-type=pdf

For anything beyond a handful of files, a shell loop gives you per-file control over names and error handling:

for f in assets/*.svg; do
  inkscape "$f" --export-type=png \
    --export-filename="dist/$(basename "$f" .svg).png" \
    --export-width=512 --export-height=512 \
    --export-overwrite || exit 1
done

Run this from the repository root in your build environment. The || exit 1 matters: without it, one malformed SVG fails silently and you ship a partial asset set.

Limits and common mistakes

DPI and one-sided dimensions. PNG export defaults to 96 DPI. If you specify only a width, the height is derived from the document's aspect ratio at that DPI, which can produce off-by-one or unexpected sizes depending on the SVG's units. Always set both dimensions, or set --export-dpi explicitly, for reproducible output.

Fonts. Text is rendered using the fonts installed on the machine running the export. If the build server lacks the design font, text is substituted and metrics change — line breaks shift and labels can overflow. Install the fonts on the export machine, or convert text to paths in the source SVG. Practical check: export one text-heavy file on the target machine and visually compare it against a reference render from the design environment.

Headless quirks. Pure export generally works without a display, but some builds and certain extension-based operations still try to connect to an X server. If a headless job fails with display-related errors, wrapping the command in xvfb-run is the standard workaround:

xvfb-run -a inkscape input.svg --export-type=png --export-filename=out.png

Mixed-version scripts. If a legacy script "used to work" and now produces nothing, grep it for -e, -z, or -E before assuming the SVG is broken — those are 0.92-era flags.

A quick sanity checklist

1. inkscape --version reports 1.0 or later.
2. Width, height, and export area are set explicitly in the script.
3. --export-overwrite is present so CI never blocks on a prompt.
4. Two consecutive exports produce identical files.
5. A text-bearing SVG renders with the correct font on the export machine.

With those in place, Inkscape's CLI is a dependable, scriptable renderer — no GUI session, no manual export dialogs, and output you can diff between builds.