Scripting Inkscape Raster Exports: Flags, Pitfalls, and a Build Pipeline

The export drift problem

Design pipelines often break in a boring place: the raster export step. A designer opens an SVG, picks Export PNG Image, eyeballs the dimensions, and saves the file. Later, someone else exports the same icon at a different DPI, or forgets to set the background to transparent, or nudges the canvas before saving. The source SVG stays correct, but the shipped PNG slowly diverges from it. In a repository with dozens of icons, that drift is expensive to detect and tedious to fix.

Headless export as a build step

Inkscape can run without opening its graphical interface. This is often called headless operation: the program starts, processes a file, writes output, and exits, all from a terminal. For engineering teams, this turns export from a manual chore into a scriptable build step.

The catch is syntax. Around the 1.0 release, Inkscape changed its command-line interface significantly. Legacy flags such as --export-png were deprecated or removed. Modern 1.x builds expect --export-type and --export-filename. If you are writing a script today, verify the exact flag names against your installed version rather than copying commands from older tutorials.

Controlling the output explicitly

Graphic dialogs hide defaults. The command line does not. Every property that a dialog might pre-fill becomes an explicit choice:

• Area: --export-area-drawing crops to the drawn objects; --export-area-page uses the page boundaries; explicit coordinates are also possible.
• Resolution: --export-dpi sets the raster density.
• Background: --export-background-opacity controls whether the PNG has a transparent or opaque background.

These flags make batch operations predictable, but they also remove the safety net of dialog defaults. You must decide what "correct" means for your assets.

A worked example

The following shell script converts a single SVG to PNG. Run it from your project root. It assumes Inkscape 1.x is installed and available on your PATH. Replace assets/icon.svg and build/icon.png with your real paths.

#!/usr/bin/env bash
# Run from the repository root. Requires Inkscape 1.x on PATH.
set -euo pipefail

INPUT="assets/icon.svg"
OUTPUT="build/icon.png"

mkdir -p "$(dirname "$OUTPUT")"

if ! inkscape --export-type=png \
     --export-filename="$OUTPUT" \
     --export-dpi=96 \
     --export-area-drawing \
     --export-background-opacity=0 \
     "$INPUT" 2>build/export-warnings.log; then
  echo "Inkscape export failed. Check build/export-warnings.log" >&2
  exit 1
fi

# Inkscape may return 0 even when fonts are missing; inspect stderr.
if [ -s build/export-warnings.log ]; then
  echo "Warnings detected during export; review build/export-warnings.log" >&2
fi

Expected checks: after running, confirm that build/icon.png exists and that its pixel dimensions match your expectation. The script does not validate visual fidelity; it only checks that Inkscape exited successfully.

Risks: Inkscape can emit warnings without a non-zero exit code. A missing font or a broken image link may produce a PNG that looks wrong but still returns success. That is why the script captures standard error to a log file and alerts you if the log is non-empty.

The fidelity trade-off

Headless export skips interactive preview. You lose the immediate visual confirmation that a filter or a live path effect (an editable, non-destructive operation attached to a path) rendered as intended. In a graphical session, you would see the canvas. In a terminal, you see only exit codes and log output.

This gap widens when the rendering environment differs from the design environment. Fontconfig—the system library that resolves font names to files—may map a typeface differently on a continuous integration server than on a designer's workstation. Complex filters may also produce subtle pixel differences. The command-line interface is deterministic for a given environment, but it is not automatically identical across environments.

Verification before you rely on it

Before wiring Inkscape into an automated pipeline, confirm that your installed build behaves as expected. Run inkscape --version and inkscape --help to inventory the supported flags. Then export one known SVG via the command line and compare the result against a manual GUI export. Check dimensions, file size, and a visual spot-check of the pixels. If they match, your headless setup is likely consistent with your design workflow. If they do not, inspect the release notes or manual page for your specific minor version—flag behavior can shift between 1.x releases.

Actionable next step

Pick one asset that is currently exported by hand. Script its export using the pattern above, commit the SVG source to version control, and run the script in your local terminal. Compare the output to the last manual export. Once parity is confirmed, promote the script to your continuous integration pipeline so that raster assets are rebuilt from source rather than copied from a designer's desktop.