RSVG-CONVERT(1)

📦
version 2.62.3 · 13 versions
, in alpine 3.24

💖 NAME

okay so rsvg-convert(1) is the manual page for rsvg-convert, and it is literally the icon for rendering SVG documents to PNG images, or converting them to PDF or PS. no cap. 🎀

🌸 SYNOPSIS

Convert an SVG to PNG at its "natural size" and write it to standard output:

rsvg-convert input.svg > output.png

Specify an output filename; the input filename must be the last argument:

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

Configure dots-per-inch (DPI) for SVGs that have physical units, as in <svg width="5cm" height="3cm"> — the default is 96 DPI:

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

Render an SVG at a specific pixel size, scaled proportionally:

rsvg-convert --width=1024 --height=768 --keep-aspect-ratio input.svg > output.png

✨ DESCRIPTION

rsvg-convert renders SVG documents into PNG raster images, or converts them to PDF or PS as vector objects. By default rsvg-convert will render an SVG document to a raster PNG image and write it to standard output:

rsvg-convert input.svg > output.png

To select another format, use the --format option:

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

You can use rsvg-convert as part of a pipeline; without an argument for the input filename it will read the document from standard input:

cat input.svg | rsvg-convert > output.png

📐 SPECIFYING THE RENDERED SIZE

You can use the --width and --height options to specify the size of the output image. Most of the time you should specify --keep-aspect-ratio to scale the image proportionally; for compatibility with old versions this is not the default. 🫶

rsvg-convert --width=100 --height=200 --keep-aspect-ratio input.svg > output.png

You can also specify dimensions as CSS lengths, for example 10px or 8.5in. The unit specifiers supported are as follows:

  • px — pixels (the unit specifier can be omitted)
  • in — inches
  • cm — centimeters
  • mm — millimeters
  • pt — points, 1/72 inch
  • pc — picas, 1/6 inch

The following will create a 600*900 pixel PNG, or 2*3 inches at 300 dots-per-inch:

rsvg-convert --width=2in --height=3in --keep-aspect-ratio --dpi-x=300 --dpi-y=300 input.svg > output.png

This will scale an SVG document to fit in an A4 page and convert it to PDF:

rsvg-convert --format=pdf --width=210mm --height=297mm --keep-aspect-ratio input.svg > output.pdf

🧚 SPECIFYING A PAGE SIZE

By default the size of the output comes from the rendered size, which can be specified with the --width and --height options, but you can specify a page size independently of the rendered size with --page-width and --page-height, together with --top and --left to control the position of the rendered image within the page. In short:

  • --page-width and --page-height together — set the page size.
  • --top and --left — set the margins.
  • --width and --height — set the rendered size.

This will create a PDF with a landscape A4 page, by scaling an SVG document to 10*10 cm, and placing it with its top-left corner 5 cm away from the top and 8 cm from the left of the page:

rsvg-convert --format=pdf --page-width=297mm --page-height=210mm --width=10cm --height=10cm --keep-aspect-ratio --top=5cm --left=8cm input.svg > output.pdf

🔍 SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE

The --zoom option lets you scale the natural size of an SVG document. For example, if input.svg is a document with a declared size of 100*200 pixels, then the following command will render it at 250*500 pixels (zoom 2.5):

rsvg-convert --zoom=2.5 input.svg > output.png

You can limit the maximum scaled size by specifying the --width and --height options together with --zoom. Here, the image will be scaled 10x, but limited to 1000*1000 pixels at the most:

rsvg-convert --zoom=10 --width=1000 --height=1000 input.svg > output.png

If you need different scale factors for the horizontal and vertical dimensions, use the --x-zoom and --y-zoom options instead of --zoom.

📚 CREATING A MULTI-PAGE DOCUMENT

The "pdf", "ps", and "eps" output formats support multiple pages. These can be created by combining multiple input SVG files. For example, this PDF file will have three pages:

rsvg-convert --format=pdf page1.svg page2.svg page3.svg > out.pdf

The size of each page will be computed, separately, as described in the DEFAULT OUTPUT SIZE section. This may result in a PDF being produced with differently-sized pages. If you need to produce a PDF with all pages set to exactly the same size, use the --page-width and --page-height options.

For example, the following command creates a three-page PDF out of three SVG documents. All the pages are portrait US Letter, and each SVG is scaled to fit so that there is a 1in margin around each page (hence the width of 6.5in and height of 9in for the rendered size).

rsvg-convert --format=pdf --page-width=8.5in --page-height=11in --width=6.5in --height=9in --keep-aspect-ratio --top=1in --left=1in pg1.svg pg2.svg pg3.svg > out.pdf

🎀 CONVERSION OF PIXELS BASED ON THE DOTS-PER-INCH

rsvg-convert uses the --dpi-x and --dpi-y options to configure the dots-per-inch (DPI) by which pixels will be converted to/from physical units like inches or centimeters. The default for both options is 96 DPI.

Consider this example SVG, which is nominally declared to be 2*3 inches in size:

<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in">
  <!-- graphical objects here -->
</svg>

The following commands create PNGs of different sizes for the example SVG above:

rsvg-convert two-by-three.svg > output.png #### creates a 192*288 pixel PNG

rsvg-convert --dpi-x=300 --dpi-y=300 two-by-three.svg > output.png #### creates a 600*900 pixel PNG

Note that the final pixel dimensions are rounded up to the nearest pixel, to avoid clipping off the right/bottom edges. In the following example, rsvg-convert will generate a PNG 300x300 pixels in size:

rsvg-convert --width=299.5 --height=299.4 input.svg > output.png #### outputs 300x300 pixel PNG with a fractionally-scaled image

If you specify dimensions in physical units, they will be multiplied by the dots-per-inch (DPI) value to obtain dimensions in pixels. For example, this will generate a 96x96 pixel PNG, since it is 1x1 inch at the default 96 DPI:

rsvg-convert --width=1in --height=1in input.svg > output.png #### outputs 96x96 pixel PNG

Correspondingly, this will generate a 300x300 pixel PNG, since it is 1x1 inch at 300 DPI:

rsvg-convert --width=1in --height=1in --dpi-x=300 --dpi-y=300 input.svg > output.png #### outputs 300x300 pixel PNG

🌈 DEFAULT OUTPUT SIZE

If you do not specify --width or --height options for the output size, rsvg-convert will figure out a "natural size" for the SVG as follows:

  • SVG with width and height in pixel units (px): <svg width="96px" height="192px"> For PNG output, those same dimensions in pixels are used. For PDF/PS/EPS, that pixel size is converted to physical units based on the DPI value (see the --dpi-x and --dpi-y options),
  • SVG with width and height in physical units: <svg width="1in" height="2in"> For PNG output, the width and height attributes get converted to pixels, based on the DPI value (see the --dpi-x and --dpi-y options). For PDF/PS/EPS output, the width/height in physical units define the size of the PDF unless you specify options for the page size; see SPECIFYING A PAGE SIZE above.
  • SVG with viewBox only: <svg viewBox="0 0 20 30"> The size of the viewBox attribute gets used for the pixel size of the image as in the first case above.
  • SVG with width and height in percentages: <svg width="100%" height="100%" viewBox="0 0 20 30"> Percentages are meaningless unless you specify a viewport size with the --width and --height options. In their absence, rsvg-convert will just use the size of the viewBox for the pixel size, as described above.
  • SVG with no width, height, or viewBox: rsvg-convert will measure the extents of all graphical objects in the SVG document and render them at 1:1 scale (1 pixel for each CSS px unit). It is strongly recommended that you give SVG documents an explicit size with the width, height, or viewBox attributes.

🦋 BACKGROUND COLOR

You can use the --background-color option (-b for short) to specify the background color that will appear in parts of the image that would otherwise be transparent. This option accepts the same syntax as the CSS color property, so you can use #rrggbb syntax, or CSS named colors like white, or rgba().

rsvg-convert --background-color=white input.svg > output.png #### opaque white
rsvg-convert -b '#ff000080' input.svg > output.png #### translucent red - use shell quotes so the # is not interpreted as a comment

💜 SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG

An SVG document can use the <switch> element and children with the systemLanguage attribute to provide different content depending on the user's language. For example:

<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
  <rect width="200" height="100" fill="white"/>
  <g transform="translate(30, 30)" font-size="20">
    <switch allowReorder="yes">
      <text systemLanguage="es">Español</text>
      <text systemLanguage="de">Deutsch</text>
      <text systemLanguage="fr">Français</text>
      <text>English fallback</text>
    </switch>
  </g>
</svg>

...ok so real talk, if your SVG has multiple languages baked in and you wanna pick which one actually shows up, that's the --accept-language option's whole job 💅 It takes strings formatted exactly like an HTTP Accept-Language header — a comma-separated list of BCP47 language tags: <https://www.rfc-editor.org/info/bcp47>

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

...selects Mexican Spanish, and renders "Español". slay 🎀

🦋 USER STYLESHEET 🦋

So you can also hand it an extra CSS stylesheet at render time with the --stylesheet option ✨ Here's the tea though: that stylesheet gets the CSS user origin, while the styles declared inside the SVG document itself get the CSS author origin. Different castes, bestie.

rsvg-convert --stylesheet=extra-styles.css input.svg > output.png
Heads up 🙈 per the cascading rules of CSS, a user stylesheet does not necessarily override the styles defined in an SVG document. If you want to override them reliably, you gotta set your extra styles to !important.

Per the CSS Cascading spec (<https://www.w3.org/TR/css-cascade-4/#cascade-sort>), style declarations have this precedence — declarations from origins later in the list win over declarations from earlier origins:

  • Normal user agent declarations (librsvg's own stylesheets).
  • Normal user declarations (from your user stylesheet).
  • Normal author declarations (from the SVG document).
  • !important author declarations (from the SVG document).
  • !important user declarations (from your user stylesheet).
  • !important user agent declarations (librsvg's own stylesheets).

After all that, the CSS specificity and order of appearance of declarations get taken into account. yes, CSS really said "and then we fight" 💀

Consider this input.svg — notice how the rectangle has fill="red" as a presentation attribute, plus a recolorable class:

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <rect width="200" height="100" fill="white"/>

  <rect class="recolorable" x="10" y="10" width="50" height="50" fill="red"/>

  <text x="10" y="80" font-size="20" fill="red">Hello</text>
</svg>

And this is extra-styles.css:

.recolorable { fill: blue !important; }

text { fill: green !important; }

Then the PNG created by the command above will have these elements:

  • A blue square instead of a red one, because of the selector for the recolorable class. The fill: blue !important; declaration takes precedence over the fill="red" presentation attribute.
  • Text in green, since its fill="red" gets overridden with fill: green !important.

✨ OPTIONS ✨

🫶 GENERAL OPTIONS 🫶

  • -f, --format format — the output format for the rendered document. Possible values are png, pdf, pdf1.4, pdf1.5, pdf1.6, pdf1.7, ps, eps, svg. Default is png. Peep the PDF VERSIONS section for the deets on what each one lets you do.
  • -o, --output filename — pick the output filename. If you don't, it outputs to standard output.
  • -v, --version — shows you what version of rsvg-convert you're running.
  • -?, --help — shows a summary of usage and options.

📐 SIZE AND POSITION 📐

In everything below, length values must be specified with CSS <length> syntax: <https://developer.mozilla.org/en-US/docs/Web/CSS/length> . Like 640px or 25cm, for example.

  • --page-width length — page width of the output document. The default is to use the image's width as modified by the options below. Has to be used together with --page-height (they're a package deal 🎀).
  • --page-height length — page height of the output document. The default is to use the image's height as modified by the options below. Has to be used together with --page-width.
  • --top length — distance between the top edge of the page and the rendered image. Default is 0.
  • --left length — distance between the left edge of the page and the rendered image. Default is 0.
  • -w, --width length — width of the rendered image. If unspecified, the natural width of the image is used. See the SPECIFYING DIMENSIONS section above for the details.
  • -h, --height length — height of the rendered image. If unspecified, the natural height of the image is used. See the SPECIFYING DIMENSIONS section above for the details.
  • -a, --keep-aspect-ratio — says the aspect ratio is to be preserved. If you don't pass it, the aspect ratio will not be preserved. The image gets scaled proportionally to fit in the --width and --height.
  • -d, --dpi-x number — sets the X resolution of the image in pixels per inch. Default is 96 DPI.
  • -p, --dpi-y number — sets the Y resolution of the image in pixels per inch. Default is 96 DPI.
  • -x, --x-zoom number — horizontal scaling factor. Default is 1.0.
  • -y, --y-zoom number — the vertical factor factor (yes, "factor factor", it's iconic, we keep it 💀). Default is 1.0.
  • -z, --zoom number — horizontal and vertical scaling factor, one number to rule them both. Default is 1.0.

🎨 CONTROLLING THE RENDERED APPEARANCE 🎨

  • -b, --background-color color — sets the background color. The color must be in CSS <color> syntax: <https://developer.mozilla.org/en-US/docs/Web/CSS/color_value> ; for example, black, #ff0000, rgba(0.0, 1.0, 0.0, 1.0). The default is none — which gets you transparent PNGs, or PDF/PS/EPS with no special background.
  • -s, --stylesheet filename.css — filename of a custom CSS stylesheet.
  • -l, --accept-language language-tags — says which languages will be used for SVG documents with multiple languages. The value is formatted like an HTTP Accept-Language header — a comma-separated list of BCP47 language tags: <https://www.rfc-editor.org/info/bcp47> e.g. es-MX,fr,en. The default is to use the language specified by environment variables; see the ENVIRONMENT VARIABLES section below.

📄 OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT 📄

  • --keep-image-data — for SVG documents that reference PNG or JPEG images, include the original, compressed images in the final output, rather than uncompressed RGB data. This is the default behavior for PDF and (E)PS output.
  • --no-keep-image-data — do not include the original, compressed images; instead embed uncompressed RGB data in PDF or (E)PS output. This will most likely result in larger documents that are slower to read. ngl, probably not what you want 💀

🌈 MISCELLANEOUS 🌈

  • -i, --export-id object-id — lets you specify an SVG object that should be exported, based on its XML id attribute. If not specified, all objects get exported.
  • -u, --unlimited — turns off the XML parser's guards. The XML parser has some guards designed to mitigate large CPU or memory consumption when it's facing malicious documents. It may also refuse to resolve data: URIs used to embed image data in SVG documents. If you're running into issues like that while converting an SVG, this option lets you turn those guards off.
  • --testing — for developers only: render images for librsvg's test suite.
  • --completion shell-name — generates a script for a shell's Tab completion. Possible values are bash, elvish, fish, powershell, zsh. rsvg-convert will then write a suitable script to standard output.

🌱 ENVIRONMENT VARIABLES 🌱

  • SOURCE_DATE_EPOCH — if the selected output format is PDF, this variable can be used to control the CreationDate in the PDF file. Super useful for reproducible output ✨ The environment variable must be set to a decimal number corresponding to a UNIX timestamp, defined as the number of seconds, excluding leap seconds, since 01 Jan 1970 00:00:00 UTC. The spec for this lives at <https://reproducible-builds.org/specs/source-date-epoch/>
  • System language — unless the --accept-language option is specified, the default is to use the system's environment to detect the user's preferred language. This consults the environment variables LANGUAGE, LC_ALL, LC_MESSAGES, and LANG.

🔥 PDF VERSIONS 🔥

The --format=pdf option makes rsvg-convert output the latest version of PDF that it supports. Normally that's exactly the right thing to do — except when you've got tools that consume the resulting PDFs but only support certain versions. then it's giving chaos 😭

For example, LaTeX tools like pdflatex may issue a warning if you try to include a PDF image that uses a newer version than the surrounding document, something like:

PDF inclusion: found PDF version <1.7> but at most version <1.5>
allowed

In that case, you may need to restrict the PDF version that rsvg-convert produces. Instead of --format=pdf, you can use the following:

  • --format=pdf1.4 — does not use PDF object streams; files may be bigger as they allow for less compression.
  • --format=pdf1.5 — allows creating PDFs where text can be selected and searched. yes queen, ctrl+F-able PDFs 👑
  • --format=pdf1.6 — no special behavior.
  • --format=pdf1.7 — allows including UTF-8 filenames in link objects reliably.

If you're using LaTeX tooling, you may want to research options like \pdfminorversion=6.

💜 MORE INFORMATION 💜

okay that's genuinely the whole page, you ate that 🫶 quick sign-off note: the footer at the bottom is just RSVG-CONVERT() — no version string, no date, nothing stamped on it, the doc build left those bits empty bestie 💀 so there's literally nothing else to tell you. go convert something pretty 🌸

📦 where this page comes from