User Guide

This guide provides an overview of using psd2svg for converting PSD files to SVG format.

For detailed information on specific topics, see the feature-specific guides linked below.

Quick Start

Command Line

Convert a PSD file to SVG with a single command:

psd2svg input.psd output.svg

For comprehensive command-line documentation, see Command Line Usage.

Python API

Use the convert() convenience function for simple conversions:

from psd2svg import convert

convert('input.psd', 'output.svg')

For advanced usage with the SVGDocument class, see the sections below.

Python API Reference

The convert() Function

For simple one-step conversions, use the convert() convenience function:

from psd2svg import convert

# Basic conversion with embedded images
convert('input.psd', 'output.svg')

# With external images in same directory
convert('input.psd', 'output.svg', image_prefix='.')

# With external images in subdirectory
convert('input.psd', 'output.svg', image_prefix='images/img')

# With custom image format
convert('input.psd', 'output.svg',
        image_prefix='images/img',
        image_format='webp')

# With custom options
convert('input.psd', 'output.svg',
        enable_title=False,
        text_letter_spacing_offset=-0.015)

Parameters:

  • input_path (str): Path to input PSD file

  • output_path (str): Path to output SVG file

  • embed_images (bool): Whether to embed images as data URIs (default: True if no image_prefix)

  • image_prefix (str, optional): Prefix for external image files, relative to the output SVG file’s directory

  • image_format (str): Image format - ‘png’, ‘jpeg’, or ‘webp’ (default: ‘webp’)

  • enable_title (bool): Enable insertion of <title> elements with layer names (default: False)

  • text_letter_spacing_offset (float): Global offset (in pixels) to add to all letter-spacing values (default: 0.0)

SVGDocument Class

The SVGDocument class is the main interface for working with SVG documents and their resources.

Creating SVGDocument

From PSD File

Create an SVGDocument from a PSD file:

from psd2svg import SVGDocument
from psd_tools import PSDImage

# Load PSD file
psdimage = PSDImage.open("input.psd")

# Convert to SVGDocument
document = SVGDocument.from_psd(psdimage)

# Save to file
document.save("output.svg")

Common Options:

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")

# Disable text conversion (rasterize text)
document = SVGDocument.from_psd(psdimage, enable_text=False)

# Disable title elements
document = SVGDocument.from_psd(psdimage, enable_title=False)

Saving SVG Documents

With Embedded Images

Embed all images as base64-encoded data URIs within the SVG file:

document.save("output.svg")  # Default behavior

With External Images

Export images to external files. The image_prefix is interpreted relative to the output SVG file’s directory:

# Images in same directory as SVG
document.save("output.svg", image_prefix=".")
# => output.svg, 01.webp, 02.webp, ...

# Images in subdirectory
document.save("output.svg", image_prefix="images/img")
# => output.svg, images/img01.webp, images/img02.webp, ...

For more details on image handling, see Image Handling.

With Embedded Fonts

Embed fonts directly in the SVG file for self-contained documents:

# Embed fonts as base64-encoded data URIs
document.save("output.svg", embed_fonts=True)

# Embed fonts with WOFF2 compression and subsetting
document.save("output.svg", embed_fonts=True, font_format="woff2")

For more details on font handling and subsetting, see Font Handling.

Getting SVG as String

Get the SVG content as a string instead of saving to a file:

svg_string = document.tostring()
print(svg_string)  # => "<svg>...</svg>"

# With external images (relative paths)
svg_string = document.tostring(image_prefix="images/img")

Export and Load

Export the document to a dictionary format:

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")
document = SVGDocument.from_psd(psdimage)

# Export document and resources
data = document.export()
# => {"svg": "<svg>...</svg>", "resources": {"001": <PIL.Image>, ...}}

# Load from exported data
restored = SVGDocument.load(data["svg"], data["resources"])

This is useful for serialization or transferring documents between processes.

Rasterization

Convert SVG documents to raster images using the built-in rasterizer support.

Using Built-in Method

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")
document = SVGDocument.from_psd(psdimage)

# Rasterize to PIL Image
image = document.rasterize()
image.save('output.png')

# Rasterize with custom DPI
image = document.rasterize(dpi=300)
image.save('output_high_res.png')

Using Rasterizer Directly

from psd2svg.rasterizer import ResvgRasterizer

rasterizer = ResvgRasterizer(dpi=96)

# Rasterize from file
image = rasterizer.from_file('output.svg')
image.save('rasterized.png')

For comprehensive rasterization documentation, see Rasterizers.

Feature Guides

For detailed information on specific features, see these dedicated guides:

  • :doc:`command-line` - Complete command-line interface reference

  • :doc:`images` - Image embedding, formats, and optimization

  • :doc:`fonts` - Font embedding and subsetting

  • :doc:`rasterizers` - SVG to raster image conversion

  • :doc:`configuration` - Advanced configuration options

Best Practices

For Web Delivery

Optimize for web applications:

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")
document = SVGDocument.from_psd(psdimage)

document.save(
    "output.svg",
    embed_fonts=True,           # Embed fonts
    image_prefix="images/img",  # External images
    image_format="webp",        # Best compression
    font_format="woff2",        # Font subsetting
    enable_title=False          # Remove layer names
)

Topics covered:

For Print Quality

Optimize for print or archival:

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")
document = SVGDocument.from_psd(psdimage)

document.save(
    "output.svg",
    image_prefix="images/img",  # External images
    image_format="png"           # Lossless format
)

# Rasterize at high DPI for print
image = document.rasterize(dpi=300)
image.save("output_print.png")

Topics covered:

For Maximum Compatibility

Optimize for maximum compatibility across viewers:

from psd2svg import SVGDocument
from psd_tools import PSDImage

psdimage = PSDImage.open("input.psd")

# Rasterize text, use simple paths
document = SVGDocument.from_psd(
    psdimage,
    enable_text=False,        # Rasterize text
    enable_live_shapes=False  # Use paths instead of primitives
)

document.save(
    "output.svg",
    image_format="png"  # Universal format
)

Topics covered:

Error Handling

Always wrap conversion operations in try-except blocks:

from psd2svg import SVGDocument
from psd_tools import PSDImage

try:
    psdimage = PSDImage.open("input.psd")
    document = SVGDocument.from_psd(psdimage)
    document.save("output.svg")
except FileNotFoundError:
    print("PSD file not found")
except Exception as e:
    print(f"Conversion failed: {e}")

For more error handling information, see Configuration Options.

Next Steps