1rsvg-convert(1) General Commands Manual rsvg-convert(1)
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
14 Specify an output filename; the input filename must be the last argu‐
16 ment:
17 rsvg-convert --output=output.png input.svg
19 Configure dots-per-inch (DPI), default is 96:
21 rsvg-convert --dpi-x=300 --dpi-y=300 input.svg > output.png
23 Render an SVG at a specific pixel size, scaled proportionally:
25 rsvg-convert --width=1024 --height=768 --keep-aspect-ratio in‐
27 put.svg > output.png
28
30 rsvg-convert renders SVG documents into PNG raster images, or converts
31 them to PDF or PS as vector objects. By default rsvg-convert will ren‐
32 der an SVG document to a raster PNG image and write it to standard out‐
33 put:
34 rsvg-convert input.svg > output.png
36 To select another format, use the --format option:
38 rsvg-convert --format=pdf input.svg > output.pdf
40 You can use rsvg-convert as part of a pipeline; without an argument for
42 the input filename it will read the document from standard input:
43 cat input.svg | rsvg-convert > output.png
45 SPECIFYING THE RENDERED SIZE
47 You can use the --width and --height options to specify the size of the
48 output image. Most of the time you should specify --keep-aspect-ratio
49 to scale the image proportionally; for compatibility with old versions
50 this is not the default.
51 rsvg-convert --width=100 --height=200 --keep-aspect-ratio in‐
53 put.svg > output.png
54 You can also specify dimensions as CSS lengths, for example 10px or
56 8.5in. The unit specifiers supported are as follows:
57 px pixels (the unit specifier can be omitted)
59 in inches
60 cm centimeters
61 mm millimeters
62 pt points, 1/72 inch
63 pc picas, 1/6 inch
64 The following will create a 600*900 pixel PNG, or 2*3 inches at 300
66 dots-per-inch:
67 rsvg-convert --width=2in --height=3in --keep-aspect-ratio --dpi-
69 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-
75 aspect-ratio input.svg > output.pdf
76 SPECIFYING A PAGE SIZE
78 By default the size of the output comes from the rendered size, which
79 can be specified with the --width and --height options, but you can
80 specify a page size independently of the rendered size with --page-
81 width and --page-height, together with --top and --left to control the
82 position of the rendered image within the page.
83 This will create a PDF with a landscape A4 page, by scaling an SVG doc‐
85 ument to 10*10 cm, and placing it with its top-left corner 5 cm away
86 from the top and 8 cm from the left of the page:
87 rsvg-convert --format=pdf --page-width=297mm --page-height=210mm
89 --width=10cm --height=10cm --keep-aspect-ratio --top=5cm
90 --left=8cm input.svg > output.pdf
91 SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE
93 The --zoom option lets you scale the natural size of an SVG document.
94 For example, if input.svg is a document with a declared size of
95 100*200 pixels, then the following command will render it at
96 250*500 pixels (zoom 2.5):
97 rsvg-convert --zoom=2.5 input.svg > output.png
99 You can limit the maximum scaled size by specifying the --width and
101 --height options together with --zoom. Here, the image will be scaled
102 10x, but limited to 1000*1000 pixels at the most:
103 rsvg-convert --zoom=10 --width=1000 --height=1000 input.svg >
105 output.png
106 If you need different scale factors for the horizontal and vertical di‐
108 mensions, use the --x-zoom and --y-zoom options instead of --zoom.
109 CREATING A MULTI-PAGE DOCUMENT
112 The "pdf", "ps", and "eps" output formats support multiple pages. These
113 can be created by combining multiple input SVG files. For example, this
114 PDF file will have three pages:
115 rsvg-convert --format=pdf pg1.svg pg2.svg pg3.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 --page-
122 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
126 SVG is scaled to fit so that there is a 1in margin around each page:
127 rsvg-convert --format=pdf --page-width=8.5in --page-height=11in
129 --width=6.5in --height=9in --keep-aspect-ratio --top=1in
130 --left=1in 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
136 96 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
149 192*288 pixel PNG
150 rsvg-convert --dpi-x=300 --dpi-y=300 two-by-three.svg > out‐
152 put.png #### creates a 600*900 pixel PNG
153 Note that the final pixel dimensions are rounded up to the nearest
155 pixel, to avoid clipping off the right/bottom edges. In the following
156 example, rsvg-convert will generate a PNG 300x300 pixels in size:
157 rsvg-convert --width=299.5 --height=299.4 input.svg > output.png
159 #### outputs 300x300 pixel PNG with a fractionally-scaled image
160 If you specify dimensions in physical units, they will be multiplied by
162 the dots-per-inch (DPI) value to obtain dimensions in pixels. For ex‐
163 ample, this will generate a 96x96 pixel PNG, since it is 1x1 inch at
164 the default 96 DPI:
165 rsvg-convert --width=1in --height=1in input.svg > output.png
167 #### outputs 96x96 pixel PNG
168 Correspondingly, this will generate a 300x300 pixel PNG, since it is
170 1x1 inch at 300 DPI:
171 rsvg-convert --width=1in --height=1in --dpi-x=300 --dpi-y=300
173 input.svg > output.png #### outputs 300x300 pixel PNG
174 DEFAULT OUTPUT SIZE
177 If you do not specify --width or --height options for the output size,
178 rsvg-convert will figure out a "natural size" for the SVG as follows:
179 • SVG with width and height in pixel units (px):
181 <svg width="96px" height="192px"> For PNG output, those same dimen‐
182 sions in pixels are used. For PDF/PS/EPS, that pixel size is con‐
183 verted to physical units based on the DPI value (see the --dpi-x and
184 --dpi-y options),
185 • SVG with width and height in physical units:
187 <svg width="1in" height="2in"> For PNG output, the width and height
188 attributes get converted to pixels, based on the DPI value (see the
189 --dpi-x and --dpi-y options). For PDF/PS/EPS output, the
190 width/height in physical units define the size of the PDF unless you
191 specify options for the page size; see SPECIFYING A PAGE SIZE above.
192 • SVG with viewBox only: <svg viewBox="0 0 20 30"> The size of the
194 viewBox attribute gets used for the pixel size of the image as in the
195 first case above.
196 • SVG with width and height in percentages: <svg width="100%"
198 height="100%" viewBox="0 0 20 30"> Percentages are meaningless unless
199 you specify a viewport size with the --width and --height options.
200 In their absence, rsvg-convert will just use the size of the viewBox
201 for the pixel size, as described above.
202 • SVG with no width, height, or viewBox: rsvg-convert will measure the
204 extents of all graphical objects in the SVG document and render them
205 at 1:1 scale (1 pixel for each CSS px unit). It is strongly recom‐
206 mended that you give SVG documents an explicit size with the width,
207 height, or viewBox attributes.
208 BACKGROUND COLOR
211 You can use the --background-color option ( -b for short) to specify
212 the backgroung color that will appear in parts of the image that would
213 otherwise be transparent. This option accepts the same syntax as the
214 CSS color property, so you can use #rrggbb syntax or CSS named colors
215 like white.
216 rsvg-convert --background-color=white input.svg > output.png
219 #### opaque white
220 rsvg-convert -b '#ff000080' input.svg > output.png #### translu‐
222 cent red - use shell quotes so the # is not interpreted as a
223 comment
224 SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG
227 An SVG document can use the <switch> element and children with the sys‐
228 temLanguage attribute to provide different content depending on the
229 user's language. For example:
230 <svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
232 <rect width="200" height="100" fill="white"/>
233 <g transform="translate(30, 30)" font-size="20">
234 <switch allowReorder="yes">
235 <text systemLanguage="es">Español</text>
236 <text systemLanguage="de">Deutsch</text>
237 <text systemLanguage="fr">Français</text>
238 <text>English fallback</text>
239 </switch>
240 </g>
241 </svg>
242 You can use the --accept-language option to select which language to
244 use when rendering. This option accepts strings formatted like an HTTP
245 Accept-Language header, which is a comma-separated list of BCP47 lan‐
246 guage tags: https://www.rfc-editor.org/info/bcp47
247 rsvg-convert --accept-language=es-MX input.svg > output.png ####
250 selects Mexican Spanish; renders "Español".
251 USER STYLESHEET
253 You can include an extra CSS stylesheet to be used when rendering an
254 SVG document with the --stylesheet option. The stylesheet will have
255 the CSS user origin, while styles declared in the SVG document will
256 have the CSS author origin. This means your extra stylesheet's styles
257 will override or augment the ones in the document, unless the document
258 has !important in its styles.
259 rsvg-convert --stylesheet=extra-styles.css input.svg > out‐
261 put.png
262 For example, if this is input.svg:
264 <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
266 <rect width="200" height="100" fill="white"/>
267 <rect class="recolorable" x="10" y="10" width="50" height="50" fill="red"/>
269 <text x="10" y="80" font-size="20" fill="currentColor">Hello</text>
271 </svg>
272 And this is extra-styles.css:
274 .recolorable { fill: blue; }
276 * { color: green; }
278 Then the PNG created by the command above will have these elements:
280 • A blue square instead of a red one, because of the selector for the
282 the recolorable class.
283 • Text in green, since a fill with currentColor gets substituted to the
285 value of the color property, and the * selector applies to all ele‐
286 ments.
287
291 GENERAL OPTIONS
292 -f --format [png, pdf, ps, eps, svg]
293 Output format for the rendered document. Default is png.
294 -o --output filename
296 Specify the output filename. If unspecified, outputs to stan‐
297 dard output.
298 -v --version
300 Display what version of rsvg-convert you are running.
301 --help Display a summary of usage and options.
303 SIZE AND POSITION
306 --page-width length --page-height length
307 Page size of the output document; both options must be used to‐
308 gether. The default is to use the image's width and height as
309 modified by the options below.
310 --top length
313 Distance between top edge of the page and the rendered image.
314 Default is 0.
315 --left length
317 Distance between left edge of the page and the rendered image.
318 Default is 0.
319 -w --width length
322 Width of the rendered image. If unspecified, the natural width
323 of the image is used as the default. See the section "SPECIFY‐
324 ING DIMENSIONS" above for details.
325 -h --height integer
327 Height of the rendered image. If unspecified, the natural
328 height of the image is used as the default. See the section
329 "SPECIFYING DIMENSIONS" above for details.
330 -a --keep-aspect-ratio
332 Specify that the aspect ratio is to be preserved, i.e. the image
333 is scaled proportionally to fit in the --width and --height. If
334 not specified, aspect ratio will not be preserved.
335 -d --dpi-x number
338 Set the X resolution of the image in pixels per inch. Default
339 is 96 DPI.
340 -p --dpi-y number
342 Set the Y resolution of the image in pixels per inch. Default
343 is 96 DPI.
344 -x --x-zoom number
346 Horizontal scaling factor. Default is 1.0.
347 -y --y-zoom number
349 Vertical factor factor. Default is 1.0.
350 -z --zoom number
352 Horizontal and vertical scaling factor. Default is 1.0.
353 CONTROLLING THE RENDERED APPEARANCE
356 -b --background-color [black, white, #abccee, #aaa...]
357 Specify the background color. If unspecified, none is used as
358 the default; this will create transparent PNGs, or PDF/PS/EPS
359 without a special background.
360 -s --stylesheet filename.css
362 Filename of a custom CSS stylesheet.
363 -l --accept-language [es-MX,fr,en]
365 Specify which languages will be used for SVG documents with mul‐
366 tiple languages. The string is formatted like an HTTP Accept-
367 Language header, which is a comma-separated list of BCP47 lan‐
368 guage tags: https://www.rfc-editor.org/info/bcp47. The default
369 is to use the language specified by environment variables; see
370 the section "ENVIRONMENT VARIABLES" below.
371 OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT
374 --keep-image-data
375 Include the original, compressed images in the final output,
376 rather than uncompressed RGB data. This is the default behavior
377 for PDF and (E)PS output.
378 --no-keep-image-data
380 Do not include the original, compressed images but instead embed
381 uncompressed RGB date in PDF or (E)PS output. This will most
382 likely result in larger documents that are slower to read.
383 MISCELLANEOUS
386 -i --export-id object-id
387 Allows to specify an SVG object that should be exported based on
388 its XML id. If not specified, all objects will be exported.
389 -u --unlimited
391 The XML parser has some guards designed to mitigate large CPU or
392 memory consumption in the face of malicious documents. It may
393 also refuse to resolve data: URIs used to embed image data. If
394 you are running into such issues when converting a SVG, this op‐
395 tion allows to turn off these guards.
396 --testing
398 For developers only: render images for librsvg's test suite.
399
402 SOURCE_DATE_EPOCH
403 If the selected output format is PDF, this variable can be used
404 to control the CreationDate in the PDF file. This is useful for
405 reproducible output. The environment variable must be set to a
406 decimal number corresponding to a UNIX timestamp, defined as the
407 number of seconds, excluding leap seconds, since 01 Jan 1970
408 00:00:00 UTC. The specification for this can be found at
409 https://reproducible-builds.org/specs/source-date-epoch/
410 System language
412 Unless the --accept-language option is specified, the default is
413 to use the system's environment to detect the user's preferred
414 language. This consults the environment variables LANGUAGE,
415 LC_ALL, LC_MESSAGES, and LANG.
416
419 https://gitlab.gnome.org/GNOME/librsvg
420 https://wiki.gnome.org/Projects/LibRsvg
422 http://www.w3.org/TR/SVG11/
424 http://www.w3.org/TR/SVG2
426 http://www.gnome.org/
428
431 Dom Lachowicz (cinamod@hotmail.com), Caleb Moore (c.moore@stu‐
432 dent.unsw.edu.au), Federico Mena-Quintero (federico@gnome.org), and a
433 host of others.
434 rsvg-convert(1)