SVGConverter

正體中文

SVGConverter converts PNG, JPEG, WebP, BMP, and TIFF images to SVG through a small Python API, command-line interface, and desktop GUI.

At a glance

Choose a conversion mode

Raster image
    │
    ├── embed ─────> SVG <image> (pixels preserved by default)
    └── vectorize -> SVG <path>  (optional VTracer backend)

Representative inputs

Conversion modes

• embed (default) places the original raster bytes in an SVG <image> element. It preserves the source pixels, but it is not vectorization and can be larger than the original image because of Base64 encoding. TIFF is the exception: most browsers cannot display it, so its first page is embedded as a lossless PNG instead.
• vectorize traces raster regions into SVG paths using the optional VTracer backend. It is most useful for logos, icons, illustrations, and high-contrast line art. Photographs can produce large, stylized output rather than a faithful smaller image.

Installation

SVGConverter requires Python 3.10 or newer:

python -m pip install --upgrade svgconverter

Install vectorization support when needed:

python -m pip install --upgrade "svgconverter[vectorize]"

To run the current development version instead:

git clone https://github.com/KageRyo/SVGConverter.git
cd SVGConverter
python -m pip install .

Command line

Convert one image, retaining its dimensions in the generated SVG:

svgconverter image.png
svgconverter photo.jpg --output output.svg
svgconverter logo.png --mode vectorize --vectorize-color-mode binary

To keep the source filename in a different directory:

svgconverter photo.jpg --output-dir ./svg-output

This creates svg-output/photo.svg and uses the same summary and overwrite rules as batch conversion. An existing output is skipped with exit code 0; --overwrite replaces it. A conversion failure returns exit code 1. --output selects an explicit filename for one input file and cannot be combined with --output-dir.

Convert all supported images immediately inside a directory:

svgconverter ./images --output-dir ./svg-output

Include nested directories while retaining their relative paths under the output directory:

svgconverter ./images --output-dir ./svg-output --recursive

Convert several explicit files in one batch. Shells that support glob expansion can also expand patterns such as ./images/*.png before invoking the command:

svgconverter image.png photo.jpg --output-dir ./svg-output

For batch conversion, existing output SVGs are skipped unless --overwrite is supplied; the final summary reports converted, skipped, and failed items. Supported inputs are PNG, JPG, JPEG, WebP, BMP, TIF, and TIFF (including upper-case extensions). Run svgconverter --help for all options. Vectorize mode requires the optional vectorize extra.

When a wrapper passes paths from an untrusted user or agent, add --allowed-root ./workspace to restrict resolved input and output paths to that directory. Existing symlinks that resolve outside the boundary are rejected. Without this option, the local CLI keeps its normal ability to access user-selected filesystem locations.

Embed optimization

Embed mode preserves the source raster bytes by default. Opt in to resizing or re-encoding only when a smaller raster payload is worth the quality trade-off:

svgconverter photo.jpg --max-width 1600 --jpeg-quality 82
svgconverter illustration.png --png-compress-level 9 --optimize-png

--max-width and --max-height only downscale and preserve aspect ratio. --jpeg-quality applies only to JPEG inputs; --png-compress-level and --optimize-png apply only to PNG inputs, so the same batch options are safe for mixed formats. A resized JPEG without an explicit quality uses 95. The CLI reports input, embedded-raster, and SVG sizes after each conversion or batch. These controls apply to embed mode only.

Python API

from svgconverter import (
    ConversionProgress,
    EmbedOptions,
    SVGConverter,
    convert_file,
    convert_file_with_metrics,
    convert_paths,
)

convert_file("image.png", "image.svg")
convert_file("logo.png", "logo.svg", mode="vectorize")
convert_file("workspace/image.png", allowed_root="workspace")

converter = SVGConverter(overwrite=True)
result = converter.convert_directory("./images", "./svg-output", recursive=True)
metric = convert_file_with_metrics(
    "photo.jpg",
    "photo.svg",
    embed_options=EmbedOptions(max_width=1600, jpeg_quality=82),
)


def report(progress: ConversionProgress) -> None:
    print(progress.completed, progress.total, progress.input_path)


batch = convert_paths(
    ["logo.png", "photo.jpg"], "./svg-output", progress_callback=report
)
print(batch.success_count, batch.skipped_count, batch.failure_count)
print(metric.input_bytes, metric.embedded_raster_bytes, metric.svg_bytes)

convert_file() returns the output pathlib.Path. Directory conversion returns a BatchResult containing successful output paths and per-file failures, so a bad image does not abort the entire batch. convert_paths() accepts a mix of files and directories; existing batch outputs are recorded as skips unless overwrite=True is selected. EmbedOptions is opt-in; without it, embed mode uses the original raster bytes. convert_file_with_metrics() and BatchResult.metrics report source, embedded-raster, and SVG byte sizes. Use progress_callback for each processed item; return True from should_cancel to stop cleanly before the next item. The result then has cancelled=True.

Without overwrite=True, a completed SVG is published with an atomic hard link so concurrent converters cannot replace each other's output. A collision raises OutputExistsError and is recorded as a per-file batch failure. When hard links are unsupported, Windows uses non-replacing rename, Linux uses renameat2(RENAME_NOREPLACE), and macOS uses renamex_np(RENAME_EXCL). If neither operation is available, conversion fails without publishing a partial SVG. Network-share atomicity depends on the server's implementation and has not been verified. With overwrite=True, atomic replacement is retained.

For integrations that accept untrusted path values, pass allowed_root to convert_file(), convert_file_with_metrics(), convert_directory(), convert_paths(), or SVGConverter. The converter resolves paths and rejects inputs, outputs, and symlink escapes outside that directory. The default allowed_root=None preserves the local library behavior.

GUI

Install the package and run:

svgconverter-gui

The legacy development command python main.py starts the same GUI. Select one or more files, or a folder, to convert with visible non-blocking progress and a converted/skipped/failed summary. You can cancel between files; any per-file errors are shown after the batch without closing the application. The mode choices are described by their expected result: Keep original appearance (Embed) is recommended for photos, screenshots, and general images, while Convert to vector paths (Vectorize) is recommended for logos, icons, illustrations, and high-contrast line art. The GUI offers Traditional Chinese, English, and Japanese, plus the following conversion settings:

• Select embed or vectorize mode; the first choice embeds raster data in an SVG <image>, while the second traces the image into SVG <path> elements.
• Choose an output directory, overwrite existing SVG files, and optionally include nested folders.
• Expand Advanced settings when needed to configure embed resizing, JPEG quality, PNG compression, PNG optimization, and common vectorize options. The GUI explains pixel dimensions, JPEG quality (1–95), PNG compression (0–9), and the VTracer controls in place; blank numeric fields keep the backend defaults.

After a run, the result panel reports whether the batch completed, was skipped, partially failed, or was cancelled, together with converted/skipped/failed counts. It includes source and SVG sizes when metrics are available, identifies the output location, and provides Open output folder and Convert more images actions.

Vectorize mode requires the optional vectorize extra, just like the CLI and Python API.

For a supported release, Windows users can download the standalone SVGConverter-vX.Y.Z-windows-x86_64.exe asset from the GitHub Release page; it does not require a local Python installation.

Contributing and license

See CONTRIBUTING.md for local checks and commit conventions. This project is licensed under the MIT License.