Deterministic Batch Export from Inkscape's CLI: PNG, PDF, and Multi-Page Output

The problem: GUI exports don't scale

Exporting a handful of SVGs through Inkscape's File > Export dialog is fine once. It fails when you have forty icon files, a CI pipeline that regenerates assets on every commit, or a multi-page document where only pages 2 and 5 need re-rendering. The Inkscape command-line interface (CLI) handles all three cases deterministically: same input, same flags, same output bytes, on Linux, macOS, and Windows.

This guide covers the three flags that matter most — --export-type, --export-filename, and --export-dpi — plus page selection and the version quirks that silently change your output.

Prerequisites and version assumptions

The examples assume Inkscape 1.0 or newer, where the CLI was reworked (older 0.92-era flags like --export-png were removed). Check your version first:

inkscape --version

Run this in any terminal. On macOS with the .app bundle, the binary lives at /Applications/Inkscape.app/Contents/MacOS/inkscape; either call it by full path or add it to your PATH. No special permissions are needed — exports write ordinary files to whatever directory you target.

One default changed across versions and causes real confusion: raster export DPI defaults to 96 in modern Inkscape builds (90 in very old ones), while PDF export is vector and DPI only affects embedded raster elements. Always set --export-dpi explicitly if pixel dimensions matter, rather than relying on the default.

Core pattern: one file, one export

The minimal deterministic export looks like this:

inkscape input.svg --export-type=png --export-filename=out.png --export-dpi=300

Key behaviors:

• --export-type accepts png, pdf, svg, and ps. If omitted, Inkscape infers the type from the filename extension.
• --export-filename supports %s as a placeholder for the input basename, which is what makes batch loops clean.
• By default, PNG export uses the page area. Add --export-area-drawing to crop to the actual artwork bounding box — usually what you want for icons.

Batch loop with the %s placeholder

On Linux or macOS (bash), export every SVG in a directory to 300-DPI PNG:

for f in icons/*.svg; do
  inkscape "$f" --export-type=png \
    --export-filename="png/%s.png" \
    --export-dpi=300 --export-area-drawing
done

Quote "png/%s.png" carefully. In an unquoted or double-quoted context %s survives in bash, but if you build the string through variables or find -exec, shell expansion surprises are common. Test with one file before looping.

On Windows, the placeholder escaping differs by shell. In a .bat batch file, CMD consumes %s as a variable reference, so you must double the percent sign:

for %%f in (icons\*.svg) do (
  inkscape "%%f" --export-type=png --export-filename="png/%%%%s.png" --export-dpi=300
)

Here %%f is the loop variable (batch-file syntax) and %%%%s collapses to a literal %s by the time Inkscape sees it. In PowerShell, a single %s inside double quotes works because PowerShell doesn't treat % specially — but % is an alias for ForEach-Object at the start of a pipeline, so keep it inside the quoted argument.

Selective page export

For multi-page documents (Inkscape 1.2+ pages feature), --export-page takes comma-separated numbers and ranges:

inkscape brochure.svg --export-type=pdf --export-page=1,3-5 --export-filename=excerpt.pdf

This produces a PDF containing only pages 1, 3, 4, and 5, without opening the GUI. For PNG, each selected page exports separately; combine with %s and page numbering in the filename pattern to avoid overwrites.

Verification: don't trust a zero exit code alone

Inkscape can exit successfully while producing a blank raster (for example, when the drawing area is empty or fonts are missing). Verify output rather than assuming:

• Page count and structure: run pdfinfo out.pdf (from poppler-utils) and check the Pages line matches your --export-page selection.
• Vector vs. raster: file out.pdf confirms PDF structure; for PNG, identify -format '%w x %h, %[resolution.x] DPI\n' out.png (ImageMagick) shows pixel dimensions and stored resolution. A 300-DPI export of a 90 mm-wide page should be roughly 1063 px wide — if it's 319 px, your DPI flag didn't take effect.
• Non-empty render: compare file sizes across a batch. A PNG dramatically smaller than its siblings is often blank or missing a layer.

Version and feature pitfalls

Text rendering. Older Inkscape (0.92 and earlier) handled text-to-path conversion differently, and PDF export relies on fonts being available at view time unless text is converted. For consistent output across machines — especially in CI where fonts differ — convert text to paths in the source file, or test the --export-text-to-path flag against your target version, since flag availability varies.

Live path effects. Complex path effects (Envelope Deformation, some mesh gradients) may rasterize or simplify when exported to PDF, depending on what the PDF model can represent. There is no flag that guarantees fidelity; the practical check is to open the exported PDF and inspect one representative file per batch visually, or diff rendered output against a known-good reference image.

Headless environments. On Linux servers without a display, modern Inkscape generally runs CLI exports headless without extra setup, but some builds still want D-Bus or a session bus. If you see D-Bus warnings in CI, dbus-run-session inkscape ... or setting DBUS_SESSION_BUS_ADDRESS=/dev/null usually silences them; verify on your distribution.

Recovery and reruns

Exports only write files, so recovery is simple: delete the output directory and rerun. To make runs idempotent, write to a fresh build/ directory each time rather than overwriting source-adjacent files, and keep the export script in version control next to the SVGs so the DPI and area flags are reviewable. If a batch produces inconsistent results, rerun a single file with --export-filename pointed at a scratch path and compare — this isolates whether the problem is the input file or the loop quoting.