1RSVG-CONVERT() RSVG-CONVERT()
2
6 rsvg-convert - Render SVG documents to PNG images, or convert them to
7 PDF or PS.
8
10 Convert an SVG to PNG at its "natural size" and write it to standard
11 output:
12 rsvg-convert input.svg > output.png
13 Specify an output filename; the input filename must be the last argu‐
15 ment:
16 rsvg-convert --output=output.png input.svg
17 Configure dots-per-inch (DPI) for SVGs that have physical units, as in
19 <svg width="5cm" height="3cm"> - the default is 96 DPI:
20 rsvg-convert --dpi-x=300 --dpi-y=300 input.svg > output.png
21 Render an SVG at a specific pixel size, scaled proportionally:
23 rsvg-convert --width=1024 --height=768 --keep-aspect-ratio input.svg
24 > output.png
25
27 rsvg-convert renders SVG documents into PNG raster images, or converts
28 them to PDF or PS as vector objects. By default rsvg-convert will ren‐
29 der an SVG document to a raster PNG image and write it to standard out‐
30 put:
31 rsvg-convert input.svg > output.png
32 To select another format, use the --format option:
34 rsvg-convert --format=pdf input.svg > output.pdf
35 You can use rsvg-convert as part of a pipeline; without an argument for
37 the input filename it will read the document from standard input:
38 cat input.svg | rsvg-convert > output.png
39 SPECIFYING THE RENDERED SIZE
41 You can use the --width and --height options to specify the size of the
42 output image. Most of the time you should specify --keep-aspect-ratio
43 to scale the image proportionally; for compatibility with old versions
44 this is not the default.
45 rsvg-convert --width=100 --height=200 --keep-aspect-ratio input.svg
46 > output.png
47 You can also specify dimensions as CSS lengths, for example 10px or
49 8.5in. The unit specifiers supported are as follows:
50 ┌───┬────────────────────────────┐
52 │px │ pixels (the unit specifier │
53 │ │ can be omitted) │
54 ├───┼────────────────────────────┤
55 │in │ inches │
56 ├───┼────────────────────────────┤
57 │cm │ centimeters │
58 ├───┼────────────────────────────┤
59 │mm │ millimeters │
60 ├───┼────────────────────────────┤
61 │pt │ points, 1/72 inch │
62 ├───┼────────────────────────────┤
63 │pc │ picas, 1/6 inch │
64 └───┴────────────────────────────┘
65 The following will create a 600*900 pixel PNG, or 2*3 inches at 300
67 dots-per-inch:
68 rsvg-convert --width=2in --height=3in --keep-aspect-ratio
69 --dpi-x=300 --dpi-y=300 input.svg > output.png
70 This will scale an SVG document to fit in an A4 page and convert it to
72 PDF:
73 rsvg-convert --format=pdf --width=210mm --height=297mm --keep-as‐
74 pect-ratio input.svg > output.pdf
75 SPECIFYING A PAGE SIZE
77 By default the size of the output comes from the rendered size, which
78 can be specified with the --width and --height options, but you can
79 specify a page size independently of the rendered size with
80 --page-width and --page-height, together with --top and --left to con‐
81 trol the position of the rendered image within the page. In short:
82 • --page-width and --page-height together - set the page size.
84 • --top and --left - set the margins.
86 • --width and --height - set the rendered size.
88 This will create a PDF with a landscape A4 page, by scaling an SVG doc‐
90 ument to 10*10 cm, and placing it with its top-left corner 5 cm away
91 from the top and 8 cm from the left of the page:
92 rsvg-convert --format=pdf --page-width=297mm --page-height=210mm
93 --width=10cm --height=10cm --keep-aspect-ratio --top=5cm --left=8cm
94 input.svg > output.pdf
95 SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE
97 The --zoom option lets you scale the natural size of an SVG document.
98 For example, if input.svg is a document with a declared size of 100*200
99 pixels, then the following command will render it at 250*500 pixels
100 (zoom 2.5):
101 rsvg-convert --zoom=2.5 input.svg > output.png
102 You can limit the maximum scaled size by specifying the --width and
104 --height options together with --zoom. Here, the image will be scaled
105 10x, but limited to 1000*1000 pixels at the most:
106 rsvg-convert --zoom=10 --width=1000 --height=1000 input.svg > out‐
107 put.png
108 If you need different scale factors for the horizontal and vertical di‐
110 mensions, use the --x-zoom and --y-zoom options instead of --zoom.
111 CREATING A MULTI-PAGE DOCUMENT
113 The "pdf", "ps", and "eps" output formats support multiple pages. These
114 can be created by combining multiple input SVG files. For example, this
115 PDF file will have three pages:
116 rsvg-convert --format=pdf page1.svg page2.svg page3.svg > out.pdf
117 The size of each page will be computed, separately, as described in the
119 DEFAULT OUTPUT SIZE section. This may result in a PDF being produced
120 with differently-sized pages. If you need to produce a PDF with all
121 pages set to exactly the same size, use the --page-width and
122 --page-height options.
123 For example, the following command creates a three-page PDF out of
125 three SVG documents. All the pages are portrait US Letter, and each SVG
126 is scaled to fit so that there is a 1in margin around each page (hence
127 the width of 6.5in and height of 9in for the rendered size).
128 rsvg-convert --format=pdf --page-width=8.5in --page-height=11in
129 --width=6.5in --height=9in --keep-aspect-ratio --top=1in --left=1in
130 pg1.svg pg2.svg pg3.svg > out.pdf
131 CONVERSION OF PIXELS BASED ON THE DOTS-PER-INCH
133 rsvg-convert uses the --dpi-x and --dpi-y options to configure the
134 dots-per-inch (DPI) by which pixels will be converted to/from physical
135 units like inches or centimeters. The default for both options is 96
136 DPI.
137 Consider this example SVG, which is nominally declared to be 2*3 inches
139 in size:
140 <svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in">
142 <!-- graphical objects here -->
143 </svg>
144 The following commands create PNGs of different sizes for the example
146 SVG above:
147 rsvg-convert two-by-three.svg > output.png #### creates a 192*288
148 pixel PNG
149 rsvg-convert --dpi-x=300 --dpi-y=300 two-by-three.svg > output.png
151 #### creates a 600*900 pixel PNG
152 Note that the final pixel dimensions are rounded up to the nearest
154 pixel, to avoid clipping off the right/bottom edges. In the following
155 example, rsvg-convert will generate a PNG 300x300 pixels in size:
156 rsvg-convert --width=299.5 --height=299.4 input.svg > output.png
157 #### outputs 300x300 pixel PNG with a fractionally-scaled image
158 If you specify dimensions in physical units, they will be multiplied by
160 the dots-per-inch (DPI) value to obtain dimensions in pixels. For exam‐
161 ple, this will generate a 96x96 pixel PNG, since it is 1x1 inch at the
162 default 96 DPI:
163 rsvg-convert --width=1in --height=1in input.svg > output.png ####
164 outputs 96x96 pixel PNG
165 Correspondingly, this will generate a 300x300 pixel PNG, since it is
167 1x1 inch at 300 DPI:
168 rsvg-convert --width=1in --height=1in --dpi-x=300 --dpi-y=300 in‐
169 put.svg > output.png #### outputs 300x300 pixel PNG
170 DEFAULT OUTPUT SIZE
172 If you do not specify --width or --height options for the output size,
173 rsvg-convert will figure out a "natural size" for the SVG as follows:
174 • SVG with width and height in pixel units (px): <svg width="96px"
176 height="192px"> For PNG output, those same dimensions in pixels are
177 used. For PDF/PS/EPS, that pixel size is converted to physical units
178 based on the DPI value (see the --dpi-x and --dpi-y options),
179 • SVG with width and height in physical units: <svg width="1in"
181 height="2in"> For PNG output, the width and height attributes get
182 converted to pixels, based on the DPI value (see the --dpi-x and
183 --dpi-y options). For PDF/PS/EPS output, the width/height in physical
184 units define the size of the PDF unless you specify options for the
185 page size; see SPECIFYING A PAGE SIZE above.
186 • SVG with viewBox only: <svg viewBox="0 0 20 30"> The size of the
188 viewBox attribute gets used for the pixel size of the image as in the
189 first case above.
190 • SVG with width and height in percentages: <svg width="100%"
192 height="100%" viewBox="0 0 20 30"> Percentages are meaningless unless
193 you specify a viewport size with the --width and --height options. In
194 their absence, rsvg-convert will just use the size of the viewBox for
195 the pixel size, as described above.
196 • SVG with no width, height, or viewBox: rsvg-convert will measure the
198 extents of all graphical objects in the SVG document and render them
199 at 1:1 scale (1 pixel for each CSS px unit). It is strongly recom‐
200 mended that you give SVG documents an explicit size with the width,
201 height, or viewBox attributes.
202 BACKGROUND COLOR
204 You can use the --background-color option (-b for short) to specify the
205 background color that will appear in parts of the image that would oth‐
206 erwise be transparent. This option accepts the same syntax as the CSS
207 color property, so you can use #rrggbb syntax, or CSS named colors like
208 white, or rgba().
209 rsvg-convert --background-color=white input.svg > output.png ####
210 opaque white
211 rsvg-convert -b '#ff000080' input.svg > output.png #### translucent
212 red - use shell quotes so the # is not interpreted as a comment
213 SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG
215 An SVG document can use the <switch> element and children with the sys‐
216 temLanguage attribute to provide different content depending on the
217 user's language. For example:
218 <svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
220 <rect width="200" height="100" fill="white"/>
221 <g transform="translate(30, 30)" font-size="20">
222 <switch allowReorder="yes">
223 <text systemLanguage="es">Español</text>
224 <text systemLanguage="de">Deutsch</text>
225 <text systemLanguage="fr">Français</text>
226 <text>English fallback</text>
227 </switch>
228 </g>
229 </svg>
230 You can use the --accept-language option to select which language to
232 use when rendering. This option accepts strings formatted like an HTTP
233 Accept-Language header, which is a comma-separated list of BCP47 lan‐
234 guage tags: https://www.rfc-editor.org/info/bcp47
235 rsvg-convert --accept-language=es-MX input.svg > output.png #### se‐
236 lects Mexican Spanish; renders "Español".
237 USER STYLESHEET
239 You can include an extra CSS stylesheet to be used when rendering an
240 SVG document with the --stylesheet option. The stylesheet will have the
241 CSS user origin, while styles declared in the SVG document will have
242 the CSS author origin.
243 rsvg-convert --stylesheet=extra-styles.css input.svg > output.png
244 Please note that per the cascading rules of CSS, a user stylesheet does
246 not necessarily override the styles defined in an SVG document. To
247 override them reliably, you need to set your extra styles to !impor‐
248 tant.
249 According to the CSS Cascading specification
251 (https://www.w3.org/TR/css-cascade-4/#cascade-sort), style declarations
252 have the following precedence. Declarations from origins later in the
253 list win over declarations from earlier origins:
254 • Normal user agent declarations (librsvg's own stylesheets).
256 • Normal user declarations (from your user stylesheet).
258 • Normal author declarations (from the SVG document).
260 • !important author declarations (from the SVG document).
262 • !important user declarations (from your user stylesheet).
264 • !important user agent declarations (librsvg's own stylesheets).
266 After that, the CSS specificity and order of appearance of declarations
268 get taken into account.
269 Consider the following input.svg; notice how the rectangle has
271 fill="red" as a presentation attribute, and a recolorable class:
272 <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
274 <rect width="200" height="100" fill="white"/>
275 <rect class="recolorable" x="10" y="10" width="50" height="50" fill="red"/>
277 <text x="10" y="80" font-size="20" fill="red">Hello</text>
279 </svg>
280 And this is extra-styles.css:
282 .recolorable { fill: blue !important; }
284 text { fill: green !important; }
286 Then the PNG created by the command above will have these elements:
288 • A blue square instead of a red one, because of the selector for the
290 the recolorable class. The fill: blue !important; declaration takes
291 precendence over the fill="red" presentation attribute.
292 • Text in green, since its fill="red" gets overriden with fill: green
294 !important.
295
297 GENERAL OPTIONS
298 -f format, --format=[png, pdf, pdf1.4, pdf1.5, pdf1.6. pdf1.7, ps, eps,
299 svg]
300 Output format for the rendered document. Default is png. See
301 the section "PDF VERSIONS" for more detail on what each one al‐
302 lows.
303 -o filename, --output filename
305 Specify the output filename. If unspecified, outputs to standard
306 output.
307 -v, ``--version
309 Display what version of rsvg-convert you are running.
310 --help Display a summary of usage and options.
312 SIZE AND POSITION
314 In the following, <length> values must be specified with CSS <length>
315 syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/length. For
316 example, 640px or 25cm.
317 --page-width <length> --page-height <length>
319 Page size of the output document; both options must be used to‐
320 gether. The default is to use the image's width and height as
321 modified by the options below.
322 --top <length>
324 Distance between top edge of the page and the rendered image.
325 Default is 0.
326 --left <length>
328 Distance between left edge of the page and the rendered image.
329 Default is 0.
330 -w <length>, --width <length>
332 Width of the rendered image. If unspecified, the natural width
333 of the image is used as the default. See the section "SPECIFYING
334 DIMENSIONS" above for details.
335 -h <length>, --height <length>
337 Height of the rendered image. If unspecified, the natural height
338 of the image is used as the default. See the section "SPECIFYING
339 DIMENSIONS" above for details.
340 -a, --keep-aspect-ratio
342 Specify that the aspect ratio is to be preserved, i.e. the image
343 is scaled proportionally to fit in the --width and --height. If
344 not specified, aspect ratio will not be preserved.
345 -d number, --dpi-x number
347 Set the X resolution of the image in pixels per inch. Default is
348 96 DPI.
349 -p number, --dpi-y number
351 Set the Y resolution of the image in pixels per inch. Default is
352 96 DPI.
353 -x number, --x-zoom number
355 Horizontal scaling factor. Default is 1.0.
356 -y number, --y-zoom number
358 Vertical factor factor. Default is 1.0.
359 -z number, --zoom number
361 Horizontal and vertical scaling factor. Default is 1.0.
362 CONTROLLING THE RENDERED APPEARANCE
364 -b <color>, --background-color [black, white, #abccee, #aaa...]
365 Specify the background color. If unspecified, none is used as
366 the default; this will create transparent PNGs, or PDF/PS/EPS
367 without a special background. The <color> must be specified in
368 CSS <color> syntax:
369 https://developer.mozilla.org/en-US/docs/Web/CSS/color_value.
370 For example, black, #ff0000, rgba(0.0, 1.0, 0.0, 1.0).
371 -s filename.css, --stylesheet filename.css
373 Filename of a custom CSS stylesheet.
374 -l language-tag, --accept-language [es-MX,fr,en]
376 Specify which languages will be used for SVG documents with mul‐
377 tiple languages. The string is formatted like an HTTP Ac‐
378 cept-Language header, which is a comma-separated list of BCP47
379 language tags: https://www.rfc-editor.org/info/bcp47. The de‐
380 fault is to use the language specified by environment variables;
381 see the section "ENVIRONMENT VARIABLES" below.
382 OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT
384 --keep-image-data
385 For SVG documents that reference PNG or JPEG images, include the
386 original, compressed images in the final output, rather than un‐
387 compressed RGB data. This is the default behavior for PDF and
388 (E)PS output.
389 --no-keep-image-data
391 Do not include the original, compressed images but instead embed
392 uncompressed RGB date in PDF or (E)PS output. This will most
393 likely result in larger documents that are slower to read.
394 MISCELLANEOUS
396 -i object-id, --export-id object-id
397 Allows to specify an SVG object that should be exported based on
398 its XML id attribute. If not specified, all objects will be ex‐
399 ported.
400 -u, --unlimited
402 The XML parser has some guards designed to mitigate large CPU or
403 memory consumption in the face of malicious documents. It may
404 also refuse to resolve data: URIs used to embed image data in
405 SVG documents. If you are running into such issues when convert‐
406 ing a SVG, this option allows to turn off these guards.
407 --testing
409 For developers only: render images for librsvg's test suite.
410 --completion shell-name
412 Generate a script for a shell's Tab completion. You can use
413 bash, elvish, fish, powershell, and zsh for the shell's name.
414 Rsvg-convert will then write a suitable script to standard out‐
415 put.
416
418 SOURCE_DATE_EPOCH
419 If the selected output format is PDF, this variable can be used
420 to control the CreationDate in the PDF file. This is useful for
421 reproducible output. The environment variable must be set to a
422 decimal number corresponding to a UNIX timestamp, defined as the
423 number of seconds, excluding leap seconds, since 01 Jan 1970
424 00:00:00 UTC. The specification for this can be found at
425 https://reproducible-builds.org/specs/source-date-epoch/
426 System language
428 Unless the --accept-language option is specified, the default is
429 to use the system's environment to detect the user's preferred
430 language. This consults the environment variables LANGUAGE,
431 LC_ALL, LC_MESSAGES, and LANG.
432
434 The --format=pdf option makes rsvg-convert output the latest version of
435 PDF that it supports. Normally this is the right thing to do, except
436 when you have tools that consume the resulting PDFs but only support
437 certain versions.
438 For example, LaTeX tools like pdflatex may issue a warning if you try
440 to include a PDF image that uses a newer version than the surrounding
441 document, similar to
442 PDF inclusion: found PDF version <1.7> but at most version <1.5> al‐
443 lowed
444 In this case, you may need to restrict the PDF version that rsvg-con‐
446 vert produces. Instead of --format=pdf, you can use the following:
447 --format=pdf1.4
449 Does not use PDF object streams; files may be bigger as they al‐
450 low for less compression.
451 --format=pdf1.5
453 Allows creating PDFs where text can be selected and searched.
454 --format=pdf1.6
456 No special behavior.
457 --format=pdf1.7
459 Allows including UTF-8 filenames in link objects reliably.
460 If you are using LaTeX tooling, you may want to research options like
462 \pdfminorversion=6.
463
465 Librsvg source repository and bug tracker:
466 https://gitlab.gnome.org/GNOME/librsvg
467 Wiki project page: https://wiki.gnome.org/Projects/LibRsvg
469 SVG1.1 specification: http://www.w3.org/TR/SVG11/
471 SVG2 specification: http://www.w3.org/TR/SVG2
473 GNOME project page: http://www.gnome.org/
475 RSVG-CONVERT()