qlmanage SVG to PNG: Square, White, and Sometimes Cropped

The usual answer to "how do I convert SVG to PNG on a Mac without installing anything" is qlmanage -t -s 1000 -o . file.svg. It does write a PNG. On my Mac mini running macOS 26.4.1, that PNG was a 1000 by 1000 square with an opaque white background, whatever shape the SVG was. A 200 by 100 logo took up the top-left third of the canvas. A 2000 by 500 banner lost its right-hand side. A broken SVG produced a PNG of WebKit's XML error page, and the command exited 0.

I ran 12 test SVGs through qlmanage in each of its thumbnail modes and measured every output: size, where the drawing landed, alpha. One flag, -x, fixes the shape and transparency but adds a size limit. And sips, which already ships with macOS and reads SVG, beat both. Results, the traps, and the command I'd use instead are below.

What qlmanage actually is

/usr/bin/qlmanage is a symlink into QuickLook.framework. Its man page calls it the "Quick Look Server debug and management tool" and is dated March 29, 2007. Its job is to test Quick Look generators, and thumbnails are a side effect. qlmanage -m plugins shows who draws an SVG:

public.svg-image -> /System/Library/QuickLook/Web.qlgenerator (1018.5.5)

That's the old generator format. Since macOS 15, third-party .qlgenerator plug-ins no longer load, but Apple's own still sit in /System/Library/QuickLook, and qlmanage still calls them. Web.qlgenerator renders the SVG the way a browser tab would, and that explains most of what follows.

Plain -t: a square, white, top-left snapshot

Every SVG run through qlmanage -t -s N -o dir came back as an N by N PNG with alpha 255 on every pixel. Transparent areas became white. Where the drawing ended up depended on the SVG's declared size, and it followed one rule: the SVG gets laid out in what behaves like a 300 by 300 CSS-pixel page, and that page is scaled to N.

Test SVG	Plain -t -s 512	-t -x -s 512
200x100, transparent background	512x512, drawing in a 342x171 box at top-left, rest white	512x256, corners transparent
100x300	512x512, drawing 171 px wide on the left	171x512
16x16 icon	512x512, icon is a 28 px square in the corner	512x512, scaled up, sharp
viewBox only, no width/height	512x512, stretched to full width, centered vertically	512x256
600x400	512x512, shrunk to full width, white below	512x342
2000x500	512x512, right side cropped, corner marker missing	512x128, complete
Unterminated tag	512x512 PNG of the XML error page, exit 0	"No thumbnail created", exit 0

The scale factor was N/300 for every SVG of 300 px or smaller: 1.71 at 512, 3.41 at 1024. A 50 by 50 SVG at -s 512 became an 86-pixel square. Larger SVGs were shrunk to fit the width, which worked for 600x400 and 1000x1000. The 2000x500 file wasn't shrunk far enough: I put a 20-pixel orange square in its bottom-right corner, and it's not in the output. The 300 px page is my inference from the numbers; Apple doesn't document how the generator lays anything out.

There's also no ceiling in this mode. -s 16384 wrote a 16384 by 16384 PNG, 4.8 MB, of mostly white.

-x keeps the shape and the transparency, up to a limit

-x is documented in qlmanage -h as "Use quicklookd (remote computation)". It sends the job to the Quick Look server instead of rendering in-process, and for SVG the result is completely different. Output keeps the SVG's aspect ratio with the long side equal to -s, transparent pixels stay transparent, and the 16-pixel icon was scaled up as vectors, not stretched pixels.

The catch is size. -x -s 4096 on every file I tried printed No thumbnail created and wrote nothing. I bisected the largest size that worked on four shapes:

square 16x16     max -s 1888  → 1888x1888  3,564,544 px
200x100          max -s 2670  → 2670x1335  3,564,450 px
100x300          max -s 3271  → 1091x3272  3,569,752 px
2000x500         max -s 3777  → 3777x945   3,569,265 px

Four shapes, one number: about 3.57 megapixels. One step past it and the file is silently absent. So -x is fine for icons and previews, and useless for a print-size raster.

The interesting part came when I compared it with sips. qlmanage -t -x -s 2000 and sips -s format png -Z 2000 on the same file gave pixel-identical PNGs. Same renderer underneath. sips names it in its error output: CoreSVG has logged an error.

Four ways qlmanage fails without telling you

This is what matters if qlmanage is inside a script. Every case below exited 0 or never exited:

• The -o directory doesn't exist. qlmanage prints produced one thumbnail, exits 0, and the PNG is nowhere. I hit this by accident during testing, before I noticed I'd forgotten a mkdir.
• The input file doesn't exist. In plain mode qlmanage hung. I killed the first one after 3 minutes 28 seconds; a second try hung too. With -x it printed No thumbnail created and exited 0 right away.
• The SVG is malformed. Plain mode renders WebKit's "This page contains the following errors" box into your PNG, exit 0. -x skips it, also exit 0.
• No -o at all. qlmanage opens a window to show the thumbnails and waits. The tldr page's thumbnail example has no -o; its last argument is a directory, which qlmanage treats as one more input. Over SSH, that form sat for 20 seconds until I killed it and wrote nothing.

Output is always named file.svg.png, with no flag to change it. When someone asked on Ask Different how to change qlmanage's output names, the accepted answer said "you're abusing Quick Look here already". That's fair. It's a debug tool.

What other people ran into

The Stack Exchange API finds 99 questions mentioning qlmanage across Stack Overflow, Super User and Ask Different, mostly about writing Quick Look plug-ins. Only three posts pair it with SVG. The most-viewed, a Super User question about bundling rsvg (15,306 views), lists qlmanage among the alternatives tried with two words: "horrible result". Alex Chan's 2020 write-up notes that -s is a maximum, "up to, not exactly", which is true of the JPEG he tested. For SVG in plain mode it's the opposite: the output is always exactly N by N.

Use sips instead

sips reads SVG but can't write it, and reading is all you need here. With no size flag it rasterizes at the SVG's declared size (200x100 stayed 200x100, transparent). With -Z it renders the vectors at the size you ask for:

# SVG to PNG, long side 1024, transparency kept
sips -s format png -Z 1024 logo.svg --out logo.png

# a folder, with failures reported
for f in *.svg; do
  sips -s format png -Z 1024 "$f" --out "${f%.svg}.png" >/dev/null \
    || echo "FAILED: $f" >&2
done

Against qlmanage it won on every point I tested. -Z 16000 wrote a 16000 by 8000 PNG, far past the -x cap. The broken SVG failed with CoreSVG's parser message and Error 13, exit 13, so || catches it. You choose the output name. One gap: a missing input prints not a valid file - skipping and exits 0, so a glob loop like the one above is safer than a list of paths you typed.

One flag to avoid: --resampleWidth 2000 rasterizes at the SVG's native 200 pixels and then upscales the bitmap. At the same output size, it left 67,674 soft-edged pixels against 2,837 from -Z 2000. Use -Z. (-z height width also renders as vectors, but stretches to exactly those numbers.)

Speed isn't a reason to pick qlmanage. A single qlmanage call on 100 small SVGs took 0.39 seconds, -x 0.38 seconds; a sips loop over the same files took 1.01 seconds. That's one process per file, and for most jobs the difference won't matter.

If the PNG is headed for an app icon, the next step is in PNG to ICNS on a Mac; render the 1024 size from the SVG with sips rather than scaling a smaller PNG up. The same pattern, a built-in tool whose docs promise more than it does, showed up in afconvert and textutil.

FAQ

How do I convert SVG to PNG with qlmanage?

Run qlmanage -t -x -s 1024 -o outdir file.svg. The -x flag keeps the SVG's aspect ratio and transparency; without it, macOS 26 writes a square PNG on an opaque white background. The output directory must already exist, the file is named file.svg.png, and -x refuses anything above about 3.57 megapixels. sips -s format png -Z 1024 file.svg --out file.png does the same job without those limits.

Why is my qlmanage PNG square with a white background?

Plain qlmanage -t renders SVG through Web.qlgenerator into an N by N canvas with an opaque white background, placing the drawing in the top-left corner and cropping very wide images. Adding -x sends the job to the Quick Look server, which keeps the aspect ratio and the transparent background.

Why does qlmanage say No thumbnail created?

With -x, qlmanage prints No thumbnail created when the SVG is malformed, the file does not exist, or the requested size exceeds about 3.57 megapixels (for example, -s 1888 is the largest square). It still exits with status 0, so check that the PNG exists rather than relying on the exit code.

Method: tests ran on 2026-10-09 between 13:30 and 13:50 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253) over SSH, in a scratch folder under my work directory. Inputs were 12 hand-written SVGs: six shapes from 16x16 to 2000x500 with a colored marker in the far corner, a viewBox-only file, a text file using Helvetica, and one with an unterminated tag. Each output was measured with Pillow for size, alpha and the bounding box of non-white pixels. The 3.57-megapixel cap is a bisection on four files, not a documented limit, and the 300 px layout page is inferred from the measured scale factors. Hangs were cut off with a 20-second alarm, except the first, which I killed by hand at 3:28. Stack Exchange counts come from the API search for "qlmanage" and "qlmanage svg" on the same day. I didn't test qlmanage -p previews, Finder's own thumbnails, SVGs with external images, CSS or filters, or any macOS older than 26.4.1.