Inkscape CLI and internal resource loader: relative path handling in headless environments

Question

Goal: achieve identical SVG export results when running Inkscape CLI from a developer workstation and from a headless CI server, despite differences in the current working directory and environment profile.
Constraint: the CLI treats relative paths (for linked images, fonts, extensions) as relative to the shell’s working directory, and there is no explicit option to set an alternative base directory; the production CI often runs from a different directory and may have a distinct Inkscape profile.
Uncertainty: it is unclear whether the Inkscape project intends to introduce a dedicated flag (e.g., --base-dir) to decouple resource resolution from the working directory, or if users must rely on workarounds such as absolute paths or embedded resources.
Does Inkscape provide a way to override the base directory for relative resource resolution without changing the shell’s working directory? Is there a plan to implement a --base-dir option or similar mechanism? How can users reliably test CLI export behavior to detect path‑resolution differences before deployment?

Tasadduq Burney · Answer

Direct answer
No. Inkscape's CLI does not document a --base-dir flag or equivalent that overrides the base directory for relative linked images, fonts, or extensions independently of the shell's current working directory. There is also no publicly confirmed plan to add one, so scripts should not depend on an undocumented future option.
Likely explanation versus confirmed facts
Likely explanation, needs verification for your version: SVG relative references are resolved against the document base URI when one is usable. When the loader cannot determine a usable base, it can fall back to the process working directory. That means the same SVG can resolve linked resources differently on a developer workstation and on CI if the two shells start in different directories.
Confirmed facts:

Inkscape user profiles follow platform and XDG conventions and affect default fonts, extensions, and preferences.
A profile is not a document resource base override, so matching the profile alone does not fix relative path resolution.
Option names changed between Inkscape 0.92 and 1.x; verify exact flags for your installed release.

Steps for this case

Convert linked resource references in the SVG to absolute file:// paths, or embed images and fonts as data URIs.
Add xml:base to the SVG root if your authoring pipeline can set a stable document base URI.
Run the CI export command from the same fixed working directory used locally, or set HOME and XDG_CONFIG_HOME to a matched profile before invoking Inkscape.
Use the export-only CLI form appropriate for your installed Inkscape version; do not assume 0.92 flags work in 1.x.

Verification before deployment
inkscape --version
inkscape --export-type=svg --export-filename=out.svg input.svg
sha256sum out.svg

Run the identical command from the developer CWD and from the CI CWD with the same SVG and linked resources.
Compare exit code, stderr warnings, output checksum, and rendered pixels.
Repeat with an absolute resource path or embedded data URI to isolate path resolution from font and profile differences.
Run the CI-style command with HOME and XDG_CONFIG_HOME pointed to a fresh or matched profile, without a GUI session, and confirm identical output.

Missing diagnostic detail
Which Inkscape version is installed on both the workstation and CI? The answer changes which export flags and profile paths are valid, so confirm versions before automating.
Conservative draft: verify this behavior against your installed Inkscape version before deployment.

Inkscape CLI and internal resource loader: relative path handling in headless environments

1 answer

Direct answer

Likely explanation versus confirmed facts

Steps for this case

Verification before deployment

Missing diagnostic detail

Your perspective belongs here.

0 question comments