convert-svg-to-png-cli

A Node.js package for converting SVG to PNG using headless Chromium via CLI.

If you want to convert SVG to PNG programmatically, you should instead look at convert-svg-to-png.

Install

Install using npm to access the convert-svg-to-png command from anywhere:

npm install --global convert-svg-to-png-cli

You'll need to have at least Node.js v22 or newer.

This package uses Puppeteer under-the-hood to interface with a headless Chromium instance and will download and install a headless Chromium instance for you.

Usage

Usage: convert-svg-to-png [options] [files...]


  Options:

    -V, --version          output the version number
    --no-color             disables color output
    --background <color>   specify background color for transparent regions in SVG
    --base-url <url>       specify base URL to use for all relative URLs in SVG
    --filename <filename>  specify filename for the PNG output when processing STDIN
    --height <value>       specify height for PNG
    --launch <json>        specify a json object passed to puppeteer when launching a browser
    --page <json>          specify a json object passed to puppeteer opening a page
    --rounding <type>      specify type of rounding to apply to dimensions
    --scale <value>        specify scale to apply to dimensions [1]
    --width <value>        specify width for PNG
    -h, --help             output usage information

The CLI can be used in the following ways:

• Pass SVG files to be converted to PNG files as command arguments
  • A glob pattern can be passed
  • Each converted SVG file will result in a corresponding PNG with the same base file name (e.g. image.svg -> image.png)
• Pipe SVG buffer to be converted to PNG to command via STDIN
  • If the --filename option is passed, the PNG will be written to a file resolved using its value
  • Otherwise, the PNG will be streamed to STDOUT

Environment

This package supports the use of a CONVERT_SVG_LAUNCH_OPTIONS environment variable to act as a base for the --launch option. This can make it easier to control the browser launch/connection. For example;

export CONVERT_SVG_LAUNCH_OPTIONS='{"browser": "firefox", "executablePath": "/Applications/Firefox.app/Contents/MacOS/firefox"}'

macOS

⚠️ Heads up!

If you are using this package on macOS it's important to note that there is a noticeable reduction in the quality of output files compared to other operating systems. This appears to be caused by SVG rendering within Chromium on macOS itself.

As such, there are a few options available:

1. Connect this package to a Firefox instance; however, some features may not be supported due to their lack of > support in WebDriver BiDi.
2. Run this package on Linux (e.g. Ubuntu), even if it's just within Docker, will have noticeable improvements of > macOS rendering.
3. If possible, increase the size of the input SVG as this can sometimes result in a better output.

Other Formats

If you would like to convert an SVG into a format other than PNG, check out our other converter packages below:

https://github.com/neocotic/convert-svg

Bugs

If you have any problems with this package or would like to see changes currently in development, you can do so here.

Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in CONTRIBUTING.md. We want your suggestions and pull requests!

A list of all contributors can be found in AUTHORS.md.

License

Copyright © 2025 neocotic

See LICENSE.md for more information on our MIT license.