Render SVG Files Reliably with rsvg-convert

In about ten minutes, you will turn an SVG into a PNG or PDF with a deliberate size, background and page layout. The examples use rsvg-convert 2.58.0 from the Debian-family package librsvg2-bin. You need a shell, an SVG file you are allowed to read, and write access to the destination directory. No command here needs root.

1. Check the installed version and the input

Start by checking the executable you will actually use. This matters when a machine has more than one librsvg installation, because option details and supported output formats can vary between releases.

rsvg-convert --version
file input.svg

On the system used for this guide, the first command reports rsvg-convert version 2.58.0. The second should identify the input as an SVG or XML document. If it says that the file does not exist, fix the path before changing conversion options. rsvg-convert reads the input filename last when you use --output, so keeping that ordering avoids a surprisingly common shell mistake.

2. Make a normal PNG

PNG is the default format. With no output filename, the rendered bytes go to standard output, so redirect them to a new file. This leaves the source untouched.

rsvg-convert input.svg > output.png
file output.png

The output dimensions come from the SVG's natural size. An SVG with pixel dimensions keeps those dimensions. Physical units such as in, cm and mm are converted using 96 DPI by default. For example, a 2 by 1 inch SVG produces a 192 by 96 pixel PNG at the default resolution. An SVG with only a viewBox uses that viewBox for its natural pixel size. Documents with no explicit width, height or viewBox are measured from their graphical objects, but an explicit size is easier to reproduce.

Use --output when you prefer not to use shell redirection. The input must remain the final argument.

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

If the command fails, no elevated privilege will repair a malformed SVG. Read the diagnostic, check the file path and inspect the document before trying again. To recover from an accidental overwrite, restore the destination from your backup or version control; rsvg-convert does not keep a previous copy.

3. Choose predictable dimensions

Set one or both rendered dimensions with --width and --height. Values may be pixels, or CSS lengths such as 2in, 25mm and 12pt. Add --keep-aspect-ratio when the image must not stretch. Without that option, the current version deliberately allows the width and height to scale independently.

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

The dimensions are a fitting box when aspect preservation is enabled, not a promise that every pixel will be filled. If you need exact, potentially distorted dimensions, omit the option. For print-sized raster output, combine physical dimensions with DPI:

rsvg-convert --width=2in --height=1in \
  --dpi-x=300 --dpi-y=300 input.svg > print.png

This requests a 600 by 300 pixel image. X and Y DPI are separate, so set both when you want square pixels. Alternatively, --zoom=2.5 scales both axes from the natural size. Use --x-zoom and --y-zoom only when different axis scales are intentional.

4. Produce a PDF with a page and margins

PDF, PS and EPS output remain vector-oriented where the format permits it. Select PDF explicitly and redirect standard output. The latest PDF version supported by the installed tool is selected by --format=pdf; this system reports PDF 1.7 for a simple conversion.

rsvg-convert --format=pdf input.svg > output.pdf
file output.pdf

Rendered size and page size are different concepts. --width and --height set the SVG's rendered area. --page-width and --page-height set the media, while --top and --left position the rendered area inside it. The page dimensions must be supplied together.

rsvg-convert --format=pdf \
  --page-width=210mm --page-height=297mm \
  --width=180mm --height=277mm --keep-aspect-ratio \
  --top=10mm --left=15mm input.svg > a4-page.pdf

This creates an A4 page and leaves the requested margins before fitting the SVG. Multiple SVG filenames create multiple pages for PDF, PS or EPS. Without explicit page dimensions, each page can inherit a different natural size, which is easy to miss when combining unrelated artwork.

If another application rejects the PDF because it is newer than the version it supports, choose a specific format such as pdf1.5 or pdf1.4. Check the consuming application's requirement first, since older PDF versions can reduce compression or feature support.

5. Handle transparency, language and CSS deliberately

The default background is transparent. That is correct for a logo placed over another image, but can look like a white or black rectangle depending on the viewer. Set a background when the output must be opaque.

rsvg-convert --background-color=white input.svg > white.png
rsvg-convert --background-color 'rgba(0.0, 1.0, 0.0, 1.0)' \
  input.svg > green.png

Quote colours containing #, because an unquoted hash begins a shell comment. A user stylesheet can supply CSS during rendering:

rsvg-convert --stylesheet=extra-styles.css input.svg > restyled.png

Styles in the SVG can still win through CSS precedence. Use !important in the extra stylesheet when an override must beat an author rule, and test the result rather than assuming that the file was applied. For a multilingual SVG using systemLanguage, select a language explicitly:

rsvg-convert --accept-language=es-MX input.svg > spanish.png

Without that option, the tool consults language-related environment variables such as LANG and LANGUAGE. Explicit selection makes automated output less dependent on the account running the job.

6. Use pipelines and treat untrusted SVGs carefully

Standard input makes rsvg-convert useful in a pipeline. A lone hyphen is also accepted as the input filename by this installed version.

cat input.svg | rsvg-convert --format=png > piped.png

Do not use --unlimited as a routine troubleshooting switch. librsvg has parser limits intended to reduce excessive CPU or memory use from malicious documents, and the option disables those guards. It can also permit data URIs that the guarded parser refuses. Only use it for a file you trust, in a process and environment where high resource use is acceptable. A safer first response is to reduce the input, remove unnecessary embedded data, or set a deliberate output size.

SVG can contain more than simple drawing commands. Treat downloaded or user-supplied files as untrusted input, keep output directories scoped, and avoid running conversion as root. If a batch job fails, preserve the source and its diagnostic, then retry one file at a time to identify the offending document.

Done means

• rsvg-convert --version identified the installed implementation.
• file confirmed the expected PNG or PDF output.
• The chosen dimensions, DPI, page size and aspect-ratio behaviour are explicit.
• Transparency, stylesheet and language defaults are intentional.
• Untrusted SVGs are converted without elevated privileges and without casually disabling parser limits.