How to Convert SVG to PNG with Pandoc

Short answer: Pandoc is a document converter, not an SVG rasterizer. Convert the SVG to PNG with rsvg-convert, then reference the PNG from Markdown (or another Pandoc input) and build your output.

rsvg-convert input.svg > output.png
pandoc document.md -o document.pdf

rsvg-convert is part of librsvg and renders SVG documents to raster PNG images. Pandoc’s installation guidance recommends librsvg for image formats that need conversion. See the Pandoc installation guide, rsvg-convert documentation, and Pandoc manual.

1. Install the tools

You need Pandoc and librsvg. Install them with the package manager for your operating system.

macOS

brew install pandoc
brew install librsvg

Windows

Install Pandoc from its official installer, then install the package that provides rsvg-convert:

choco install pandoc
choco install rsvg-convert

Debian or Ubuntu

sudo apt update
sudo apt install pandoc librsvg2-bin

Fedora

sudo dnf install pandoc librsvg2-tools

Verify both executables are available:

pandoc --version
rsvg-convert --version

If your shell says the command is not found, install the missing package or add its installation directory to PATH.

2. Convert an SVG to PNG

The smallest documented conversion command writes PNG bytes to standard output:

rsvg-convert input.svg > output.png

Use --output when you prefer an explicit destination:

rsvg-convert --output=output.png input.svg

Check the result before passing it to Pandoc:

file output.png

PNG is raster output. The SVG’s scalability is not retained, so choose dimensions or DPI for the final document and viewing distance.

3. Use the PNG in a Pandoc document

Create document.md:

# Release diagram

The architecture is shown below.

![System architecture](output.png)

Build HTML, DOCX, or PDF according to your installed output engine:

# HTML
pandoc document.md -o document.html

# DOCX
pandoc document.md -o document.docx

# PDF (requires a PDF engine such as LaTeX)
pandoc document.md -o document.pdf

The PDF engine and its dependencies are separate from SVG rasterization. If PDF generation fails after the PNG was created, troubleshoot the PDF engine independently.

Keep the conversion reproducible

set -eu

input="input.svg"
output="output.png"
document="document.md"

rsvg-convert --output="$output" "$input"
pandoc "$document" -o document.pdf

Quote paths so filenames containing spaces are handled correctly. In CI, install fixed versions of Pandoc and librsvg through the runner image or package lock used by your project.

4. Control PNG dimensions, aspect ratio, and DPI

Set pixel dimensions

rsvg-convert --width=1200 --height=800 input.svg > output.png

When both dimensions are supplied, the SVG may be fitted to that box. To prevent stretching, add --keep-aspect-ratio:

rsvg-convert \
  --width=1200 \
  --height=800 \
  --keep-aspect-ratio \
  input.svg > output.png

For a predictable width while preserving the source proportions, set only the width:

rsvg-convert --width=1600 --keep-aspect-ratio input.svg > output.png

Set resolution for physical units

SVGs that use physical units such as millimetres can be rendered at an explicit resolution:

rsvg-convert --dpi-x=300 --dpi-y=300 input.svg > output.png

Use a higher DPI when the PNG will be printed or placed in a document with substantial zoom. For web delivery, select dimensions based on the displayed pixel size to avoid unnecessary files.

Choose a background

PNG output is transparent by default. Add --background-color when the target requires a solid background:

rsvg-convert --background-color=white input.svg > output.png

Transparency is useful when the image sits on a colored page; a solid background can prevent unexpected dark or checkerboard rendering in downstream tools.

5. Complete examples

Convert a directory of SVG files

mkdir -p png
for svg in diagrams/*.svg; do
  name="${svg##*/}"
  base="${name%.svg}"
  rsvg-convert --output="png/$base.png" "$svg"
done

Generate a print-sized PNG

rsvg-convert \
  --dpi-x=300 \
  --dpi-y=300 \
  --background-color=white \
  --output=figure-print.png \
  figure.svg

Generate a web-sized PNG without distortion

rsvg-convert \
  --width=1600 \
  --keep-aspect-ratio \
  --output=figure-web.png \
  figure.svg

Use a relative asset path in Markdown

pandoc docs/guide.md \
  --resource-path=.:docs:docs/assets \
  -o guide.html

Make sure the PNG path in Markdown resolves from the resource paths Pandoc searches. A successful SVG conversion does not guarantee that Pandoc can find the referenced file.

6. SVG and Pandoc output choices

Converting to PNG is a separate preprocessing step. In some HTML output paths Pandoc can preserve or embed SVG, including data URIs; the inline-svg class requests an inline SVG element. That is different from creating a PNG and depends on the target renderer.

![Diagram](diagram.svg){.inline-svg}

Choose PNG when the target format or renderer has unreliable SVG support, when you need a fixed raster appearance, or when a downstream system accepts PNG only. Keep SVG when you need selectable vector markup and your output path supports it reliably.

7. Fallback: ImageMagick

If librsvg is unavailable, ImageMagick offers a separate conversion path:

magick input.svg output.png

magick is an image conversion program; it is not a Pandoc option. Install it through the official ImageMagick packages, convert the file, and then use the resulting PNG with Pandoc as shown above.

8. Troubleshooting

Symptom	Likely cause	Fix
`rsvg-convert: command not found`	librsvg is not installed or is outside `PATH`.	Install the librsvg package for your OS, then reopen the shell and run `rsvg-convert --version`.
`pandoc: command not found`	Pandoc is not installed or its directory is not on `PATH`.	Install Pandoc from the official installation guide and verify with `pandoc --version`.
PNG is stretched	Width and height force a box with a different aspect ratio.	Add `--keep-aspect-ratio`, or provide only one dimension.
PNG is blurry	The raster dimensions are too small for its display or print size.	Increase `--width`/`--height` or use explicit `--dpi-x` and `--dpi-y`.
Background appears transparent	Transparent PNG is the default.	Set `--background-color=white` or another required color.
Image missing from Pandoc output	The Markdown path cannot be resolved from the current working directory.	Correct the relative path or add `--resource-path`.
PDF reports SVG conversion failed	The PDF route is trying to handle SVG and cannot find its converter.	Convert the SVG to PNG first and confirm `rsvg-convert` is on `PATH`; also install the PDF engine required by your Pandoc command.
SVG renders differently across machines	Different librsvg versions, fonts, external assets, or SVG features.	Pin the toolchain, bundle required fonts/assets, and inspect the generated PNG as the build artifact.
External images or fonts are absent	The SVG references resources that are unavailable to the renderer.	Make resources local and accessible, or embed them in the SVG before conversion.
Malformed SVG error	The input is not valid XML or uses unsupported SVG content.	Validate the SVG, simplify unsupported features, and rerun with the smallest source that reproduces the error.

9. Performance, reliability, and file size

Convert once, reuse many times: cache the PNG in your build output when the SVG has not changed.
Use practical dimensions: very large raster dimensions increase conversion time, memory use, and document size.
Prefer deterministic inputs: embed or version external assets and use the same librsvg/Pandoc versions in local and CI builds.
Check output in CI: fail the build when conversion exits nonzero, the output file is missing, or the PNG has an unexpected zero size.
Keep source and raster artifacts: retain the SVG for future resizing and the PNG for the exact document build.

There is no Pandoc fee for this workflow. Your costs are the compute and storage used by your local machine or CI runner, plus any PDF engine installation and maintenance.

10. Or skip the browser setup

If your actual goal is a screenshot of a rendered web page rather than conversion of a local SVG file, ScreenshotNeo provides a single screenshot API request. Read the ScreenshotNeo API documentation for all parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Can Pandoc convert SVG directly to PNG?

No. Use a rasterizer such as rsvg-convert, then give the generated PNG to Pandoc.

What is the simplest command?

rsvg-convert input.svg > output.png

How do I avoid changing the SVG’s proportions?

Use --keep-aspect-ratio, usually with one dimension such as --width.

Why is my PNG background transparent?

Transparent output is the default. Add --background-color=white when you need an opaque image.

Should I use PNG or keep SVG in HTML?

Use PNG for predictable raster rendering and broad compatibility. Keep SVG when your output path reliably supports vector markup and you need scalable, selectable graphics.

Can ImageMagick replace librsvg?

Yes, as a separate image conversion tool: magick input.svg output.png. Pandoc still consumes the resulting PNG in the normal way.