Batch-Exporting SVGs with Inkscape's Headless CLI: Actions, DPI, and CI Pitfalls

The useful answer first

Inkscape can run entirely without its GUI, which makes it a practical SVG-to-PNG rasterizer and SVG normalizer inside build scripts and CI pipelines. The core invocation looks like this:

inkscape icon.svg --export-type=png --export-filename=icon-1024.png --export-width=1024

Run this from any shell where the inkscape binary is on your PATH (on Linux CI images you may need the inkscape package plus font packages; no display server is required for export operations in current 1.x releases). No special permissions are needed beyond read access to the input and write access to the output directory. The command renders icon.svg to a 1024-pixel-wide PNG, preserving aspect ratio. If it succeeds, Inkscape exits with status 0 and writes the file; check both, because a misspelled option can produce a warning rather than a hard failure in some versions.

How the pieces fit together

Three argument families do the work:

• Export arguments (--export-type, --export-filename, --export-width/--export-height, --export-dpi) control the output format and geometry.
• Actions (--actions) run a semicolon-separated list of editing commands before export, such as selecting objects, fitting the page to content, or converting text to paths.
• Stream arguments — passing - as the input or output filename reads SVG from stdin or writes to stdout, so Inkscape slots into Unix filter chains.

A worked example: normalizing an SVG before web deployment. You want the page fitted to the drawing and the result saved as plain SVG:

inkscape messy.svg --actions="select-all;object-fit-to-page;export-filename:clean.svg;export-do"

Here select-all selects every object, object-fit-to-page resizes the page to the selection bounding box, and export-filename/export-do write the result. Action names are not guessable — run inkscape --action-list on the target machine to see exactly what your installed version supports, because names have changed across releases.

Multi-density icon export

A common pipeline task is emitting one icon at several densities. A shell loop handles it:

for d in 48 96 192; do
  inkscape icon.svg --export-type=png \
    --export-filename="icon-${d}.png" --export-width="$d" || exit 1
done

Verify the result with a tool like file icon-96.png or ImageMagick's identify to confirm pixel dimensions match what you asked for.

DPI versus pixel size

--export-width and --export-height set the raster size directly in pixels. --export-dpi instead scales the document's physical units (mm, in) into pixels — 96 DPI is the SVG default, so a 96 mm-wide document exports at 96 px at default DPI, or 300 px at --export-dpi=300. For screen assets, use explicit pixel dimensions. For print-oriented output where the SVG uses physical units, DPI is the correct lever. Mixing the two without thinking is a frequent source of "my export is the wrong size" bugs.

Migration from 0.9x scripts

If you copied a command from an older tutorial and got an "unknown option" error, this is why. Inkscape 1.0 (released 2020) removed the legacy interface:

Legacy (0.9x)	Current (1.x)
--export-png=out.png	--export-type=png --export-filename=out.png
--verb=FitCanvasToDrawing	--actions="select-all;object-fit-to-page"
--without-gui	not needed; export is headless by default

Confirm what you're running with inkscape --version before debugging anything else.

Limits and common mistakes

• Quoting and semicolons. The shell eats unquoted semicolons, so --actions="a;b" must be quoted as a single argument. The most common failure mode is a silent no-op: the command exits cleanly but nothing was exported. Always assert the output file exists and is non-empty in scripts.
• Fonts. Text renders with whatever fonts exist on the machine. A CI container missing your brand font will silently substitute another. Either install fonts in the image or convert text to paths first (an action such as object-to-path on selected text, verified via --action-list).
• Linked images. SVGs referencing external raster files by relative path will render with missing images if the working directory differs. Embed images or run the export from the SVG's directory.
• Startup cost. Inkscape loads a full application per invocation — typically a second or more per file. For thousands of simple rasters, a dedicated rasterizer like rsvg-convert (librsvg) is much faster; Inkscape earns its overhead when you need its editing actions or its more complete SVG feature support.
• Filter fidelity. Complex filters and blend modes can render slightly differently across Inkscape versions. Pin the version in CI and spot-check one representative file visually against a GUI export.

A practical verification pass

Before trusting a pipeline: run inkscape --version and inkscape --action-list on the actual build host; export one representative SVG containing text and a linked image; then check the exit code, confirm the output dimensions with identify or equivalent, and open one file to eyeball font and image rendering. That catches every failure class above in a few minutes.