How to Convert SVG to PNG with Pandoc (Using librsvg)

Short answer: Pandoc does not normally rasterize a standalone SVG into a PNG. Convert the SVG first with librsvg’s rsvg-convert, then point Pandoc at the resulting PNG when you build HTML, PDF, DOCX, or another document. The core command is rsvg-convert input.svg > output.png.

What Pandoc does—and where PNG conversion fits

Pandoc is a document converter. It reads formats such as Markdown and writes formats such as HTML, PDF, and DOCX, while handing image rendering to the tools appropriate for the target format. SVG-to-PNG conversion is a separate rasterization step, normally provided by librsvg.

That distinction matters because a PDF engine can have its own image requirements. Converting the SVG first gives you a predictable PNG asset and avoids asking Pandoc or a downstream renderer to interpret SVG support differently.

Prerequisites and installation

• Pandoc: install the current package for your operating system from Pandoc’s official distribution channels.
• librsvg: provides the rsvg-convert command used for rasterization.
• A PDF engine (only for PDF output): Pandoc’s PDF writers, such as LaTeX-based workflows, have dependencies separate from SVG conversion.

On macOS, the documented Homebrew package command is:

brew install librsvg

On Windows, the documented Chocolatey package command is:

choco install rsvg-convert

After installation, verify that both commands resolve in your shell:

pandoc --version
rsvg-convert --version

If your shell reports that either command is unknown, the executable is not installed or its directory is missing from PATH.

Convert an SVG to PNG, then use it in Pandoc

1. Render the SVG at its natural size

From the directory containing the source file, run:

rsvg-convert input.svg > output.png

Alternatively, write directly to a named file:

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

rsvg-convert renders an SVG document to a raster PNG image. The output is a bitmap, so it no longer scales indefinitely like the original vector file.

2. Reference the PNG in Markdown

![Diagram](output.png)

Save that line in document.md. A relative path is resolved from the Markdown file’s location (or the working directory, depending on how your project is organized), so keep the image path correct when you run Pandoc.

3. Build the document

pandoc document.md -o document.pdf

For HTML, use an HTML output extension instead:

pandoc document.md -o document.html

The PDF command still requires a suitable PDF engine and its dependencies. Installing rsvg-convert solves SVG rasterization; it does not install or configure the PDF engine.

Choose PNG dimensions and rendering quality

Set an exact pixel box

Use --width and --height when the PNG must fit a known pixel area:

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

Providing both dimensions can stretch the artwork if the requested proportions differ from the SVG’s aspect ratio. To fit inside the box without stretching, add --keep-aspect-ratio:

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

The resulting image may be smaller than one of the requested dimensions because the original proportions are preserved.

Use DPI for physical-size SVGs

SVG files can specify physical units such as millimeters or inches. Set the horizontal and vertical resolution explicitly when the PNG is destined for print or another physical-size workflow:

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

DPI affects the pixel dimensions calculated from physical units. It does not magically add detail that is absent from the source artwork; it determines how densely the vector is sampled.

Keep transparency or add a background

PNG output is transparent by default. That is useful for logos and diagrams placed over a document background. If your publishing pipeline expects an opaque image, set a solid background with --background-color:

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

Choose the background deliberately: once rendered into the PNG, it becomes part of the pixels and cannot be removed without editing the image again.

Practical sizing examples

Web documentation

For a diagram displayed at roughly 800 pixels wide, render at that width or somewhat larger if readers may zoom:

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

Then constrain display size in your HTML or CSS rather than repeatedly rasterizing different copies.

Print-oriented PDF

For artwork expressed in physical units, use an explicit DPI and inspect the generated PDF at its intended print size:

rsvg-convert --dpi-x=300 --dpi-y=300 --keep-aspect-ratio chart.svg > chart.png
pandoc report.md -o report.pdf

The appropriate dimensions depend on the SVG’s physical size and the final page layout. A very large PNG increases file size and processing time, while a small one will look soft when enlarged.

SVG handling inside Pandoc

Pandoc can preserve or embed SVG on some output paths. In HTML output, its manual describes using img tags with data: URIs, while the inline-svg class requests an inline SVG element. That is not the same operation as producing a PNG.

Use the original SVG when your target format and renderer reliably support SVG and you need vector output. Use a pre-rendered PNG when compatibility, predictable pixels, or a renderer’s SVG limitations are more important. For PDF workflows that report SVG conversion failures, first check that rsvg-convert is installed and available on PATH.

ImageMagick as a fallback rasterizer

If librsvg is unavailable in your environment, ImageMagick provides a separate conversion path:

magick input.svg output.png

This is an ImageMagick command, not a Pandoc option. Its SVG results can differ from librsvg for fonts, filters, external resources, or unusual SVG features, so use one rasterizer consistently in a reproducible build.

Troubleshooting

“rsvg-convert: command not found”

Install librsvg (or the Windows rsvg-convert package) and restart the terminal if the installer changed PATH. Run rsvg-convert --version before retrying the conversion.

The PNG is blank or parts are missing

Inspect the SVG for external images, web fonts, remote stylesheets, filters, or scripts. A command-line renderer may not have access to those resources. Embed required assets and fonts where possible, then render again. Also open the SVG in a browser or editor to determine whether the problem is in the source rather than Pandoc.

The image is stretched

When specifying both dimensions, add --keep-aspect-ratio, or provide only the dimension you need. Check the SVG’s viewBox and width/height values if the natural proportions are unexpected.

The PNG has jagged text or thin lines

Render at a larger width or a higher DPI, then reduce the image for display. Confirm that the intended fonts are installed or embedded; substituting a font can change line breaks and stroke appearance.

Pandoc still fails while making a PDF

Separate the two stages: run rsvg-convert manually and verify that the PNG opens, then run Pandoc with the PDF engine configured for your system. An SVG rasterization problem and a missing LaTeX/PDF dependency are different failures.

The output file is unexpectedly large

Reduce pixel dimensions to the largest size your final layout needs. A transparent, high-resolution PNG can be substantially larger than the source SVG. Keep the SVG as the source of truth and regenerate the PNG when layout requirements change.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Automate the two-stage build

A simple shell sequence makes the dependency explicit and fails early if conversion does not succeed:

set -e
rsvg-convert --width=1600 --keep-aspect-ratio assets/diagram.svg > assets/diagram.png
pandoc document.md -o document.pdf

In a larger project, place generated PNGs in a build directory, keep source SVGs under version control, and regenerate whenever an SVG changes. This avoids committing multiple hand-edited raster copies and makes CI output reproducible.

Or skip the browser setup

If what you actually need is a screenshot of a rendered web page rather than conversion of a local SVG file, ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL and returns PNG, JPEG, WebP, or PDF; it is not a replacement for rasterizing a local SVG, but it can remove browser automation from web-capture jobs.

One GET request is enough (see the ScreenshotNeo API documentation):

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

Python:

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)

Node.js:

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

• Cookie banners, newsletter popups, and chat widgets are removed before the shot.
• Bot checks or CAPTCHAs, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing status.
• An MCP server lets AI agents such as Claude or Cursor call 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 screenshots. Every feature is available on every plan.

Sign up for ScreenshotNeo’s free plan to try it without a card.

FAQ

Can Pandoc convert SVG to PNG with one flag?

Not as a general standalone conversion command. Rasterize the SVG with rsvg-convert (or ImageMagick), then use the PNG in your Pandoc document.

Should I keep SVG instead of converting it?

Keep SVG when the output renderer supports it reliably and vector scalability matters. Convert to PNG when you need predictable raster compatibility or the target pipeline cannot handle SVG.

Does changing DPI improve an SVG’s original quality?

DPI changes sampling density and resulting pixel dimensions for physical-unit artwork; it does not add new detail to the vector design.

Why is my PDF still failing after I install librsvg?

Check the PDF engine and its dependencies separately. librsvg addresses SVG rendering, while Pandoc’s PDF writer requires its own installed engine.

Frequently Asked Questions

Can Pandoc convert SVG to PNG with one flag?

Not as a general standalone conversion command. Rasterize the SVG with rsvg-convert (or ImageMagick), then use the PNG in your Pandoc document.

Should I keep SVG instead of converting it?

Keep SVG when the output renderer supports it reliably and vector scalability matters. Convert to PNG when you need predictable raster compatibility or the target pipeline cannot handle SVG.

Does changing DPI improve an SVG’s original quality?

DPI changes sampling density and resulting pixel dimensions for physical-unit artwork; it does not add new detail to the vector design.

Why is my PDF still failing after I install librsvg?

Check the PDF engine and its dependencies separately. librsvg addresses SVG rendering, while Pandoc’s PDF writer requires its own installed engine.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.