svgexport: rasterising SVG through Puppeteer from the shell or Node

Rasterising happens in a real browser, not in a graphics library

svgexport is a Node.js module and command line tool for exporting SVG files to PNG and JPEG, and the mechanism is stated plainly: it uses Puppeteer for rendering SVG files. There is no native SVG rasteriser in the stack and no native image library. The tool drives a headless Chromium instance, loads the SVG, and captures the result.

That choice explains most of the tool's behaviour, strengths and awkward edges. Because the rendering happens in a browser engine, an SVG that relies on CSS, external stylesheets, embedded fonts or JavaScript behaves the way it would in a browser, which is exactly what you want when the source artwork came from a design tool that assumes a browser renderer. It also means every conversion starts a browser process, and the cost of a conversion is the cost of launching one.

The history explains the current design. The project was migrated from PhantomJS to Puppeteer by Michael Heerklotz, and the repository is a small, focused codebase with a bin directory, index.js, render.js and resize.js, plus a test directory. The package.json shows the runtime dependencies are just async at version ^3.2.0 and puppeteer at ^3.0.2, and that the test script runs mocha with expect.js as the assertion library. The command line entry point is bin/index.js.

The audience is developers with a build step that needs rasterised assets: icon pipelines, documentation generators, anything that turns vector source into a PNG for a web page.

The argument grammar covers format, quality, viewbox, size, mode and styles

The usage block in the documentation is dense but complete, and it is worth reading as a grammar rather than a flag list. The command takes an input file, an output file and then a positional sequence of options, in this order: the format, the quality, the input viewbox, the output size, the resize mode and the styles.

The format is inferred from the output file extension, or defaults to png, so most invocations never name it. Quality takes a percentage from 1% to 100% and only matters for JPEG output.

The input viewbox is expressed as left:top:width:height or width:height, and if it is omitted it is inferred from the input file. The output size can be a scale factor, a width and height pair, a width alone, or a height alone. When the output size is given as width:height, a viewbox mode decides how the aspect ratio is handled: crop slices the input to match the output ratio, pad extends it, and the default mode is crop.

The final option slot takes a CSS string that is applied to the SVG before rendering, which is the feature that makes svgexport more than a converter. You can set a background colour, restyle elements, or theme a file on the fly.

One detail is easy to miss: because the options are positional, the order matters, and the documentation shows crop and pad used in the option position.

Worked examples for scaling, cropping, quality and styling

The examples in the documentation cover the cases you actually hit.

Scaling proportionally by a factor is the simplest form.

svgexport input.svg output.png 1.5x

Scaling to a fixed width and letting the height follow is a single colon and an empty second field.

svgexport input.svg output.png 32:

Padding rather than cropping to reach a target ratio puts the mode word in front of the size.

svgexport input.svg output.png pad 32:54

Exporting a specific region of the source takes the four-part viewbox and a scale.

svgexport input.svg output.png -1:-1:24:24 1x

JPEG quality is a percentage.

svgexport input.svg output.jpg 80%

And a CSS string styles the input before it is rendered.

svgexport input.svg output.jpg "svg{background:silver;}"

The last one is the argument to try first if you need a background behind a transparent logo, since it solves the problem without editing the source file.

Batch conversion through a JSON datafile or a Node module

For anything beyond a one-off conversion, the tool accepts a datafile, which is a path to a JSON file with a specific shape.

[ {
  "input" : ["<input file>", "<option>", "<option>", ...],
  "output": [ ["<output file>", "<option>", "<option>", ...] ]
}, ...]

Input file options are merged with and overridden by output file options, so a common set of options can live at the input level and be varied per output. Instead of a JSON file, a Node module exporting the same content can be provided, which is the useful case when the list of files is computed at run time.

The module API is small.

var svgexport = require('svgexport');

svgexport.render(datafile, callback);

The datafile argument can be an object, an array of objects, or a path to a JSON file, which is the same format the command line consumes. That symmetry is the useful part: you can prototype a batch on the command line, then move the same structure into a script.

The callback style is the older Node convention rather than a promise, so integrating this into a modern pipeline means wrapping it, and the repository shows no promise-based entry point.

Installation brings Puppeteer, and there is a known permission problem

Installing the command line tool globally is a single command.

npm install svgexport -g

For use as a dependency in a project, it is saved instead.

npm install svgexport --save

The installation is where the tool's main friction lives, and the documentation names the cause. You might encounter an error while installing because of a Puppeteer issue documented at puppeteer/puppeteer#367, and the documented workaround is to repeat the install with unsafe permissions enabled.

sudo npm install -g svgexport --unsafe-perm=true

That workaround is a reasonable thing to be uneasy about, since sudo npm install with unsafe-perm gives the install script more rights than a normal install. The underlying reason is that Puppeteer downloads a browser during installation, and that download step needs to run as the user who will own the browser cache, which in a global install is often root.

The second constraint is the browser itself. Puppeteer brings Chromium with it, so a machine running svgexport needs a working Chromium download and the shared libraries it needs, and a slim container image has to be built with those dependencies in mind rather than assumed.

There is also a timeout worth knowing. By default Puppeteer has a page load timeout of 30 seconds, which might not be enough for large SVG files, and the tool exposes an environment variable to change it. The value is the number of seconds.

// One minute timeout
SVGEXPORT_TIMEOUT=60 svgexport input.svg output.png

Version pinning, licensing and a project without releases

The package metadata says version 0.4.2, and the repository has no GitHub releases at all. There is no changelog and no published artifact list to consult, so the way to consume this tool reliably is to pin the package version in your lockfile and treat upgrades as a deliberate act. The last push was on 2026-09-23 and the repository is not archived, so the code is not abandoned, but the release cadence is invisible from the outside.

There is a licensing wrinkle that is worth resolving yourself. The licence field on the repository is not filled in, while the package.json declares MIT and the documentation states that the software is available under the MIT license, with copyright (c) 2016 Ali Shakiba. Ali Shakiba is the author in the package metadata, and Michael Heerklotz is listed as a contributor for the Puppeteer migration. The two sources agree on MIT, so the intent is clear, but reading the LICENSE file in the repository is still the step that settles it for your organisation. None of this is legal advice.

The dependency footprint is the other thing to weigh. A build step that pulls in Puppeteer is a build step that pulls in a browser, and if your pipeline already has a native rasteriser available, svgexport's advantage is CSS and browser-accurate rendering rather than speed or footprint. For a repository of a few hundred icons rendered once and committed, the difference hardly matters. For a pipeline that rasterises on every build, it is worth measuring before you commit to it.

Editorial conclusion

Adopt svgexport when your pipeline already runs Node and you want a single rasteriser that handles SVG with CSS styling, cropping, padding and batch conversion without installing a desktop toolchain. Do not adopt it in a container that cannot ship Chromium, in an air-gapped build where the browser download is a problem, or when you need vector output, since the tool only writes PNG and JPEG. Before wiring it into a build, confirm your Puppeteer version can launch on your platform, set SVGEXPORT_TIMEOUT for large files, and pin the package version, since the project publishes no GitHub releases and the last commit was on 2026-09-23.

Frequently asked questions

Official sources

1. Issues
2. piqnt/svgexport on GitHub
3. README