Command line

The package provides command line tools to handle a PSD document:

psd-tools export <input_file> <output_file> [options]
psd-tools show <input_file> [options]
psd-tools debug <input_file> [options]
psd-tools -h | --help
psd-tools --version


psd-tools show example.psd  # Show the file content
psd-tools export example.psd example.png  # Export as PNG
psd-tools export example.psd[0] example-0.png  # Export layer as PNG

Working with PSD document

psd_tools.api package provides the user-friendly API to work with PSD files. PSDImage represents a PSD file.

Open an image:

from psd_tools import PSDImage
psd ='my_image.psd')

Most of the data structure in the psd-tools suppports pretty printing in IPython environment.

In [1]:'example.psd')
PSDImage(mode=RGB size=101x55 depth=8 channels=3)
  [0] PixelLayer('Background' size=101x55)
  [1] PixelLayer('Layer 1' size=85x46)

Internal layers are accessible by iterator or indexing:

for layer in psd:
    if layer.is_group():
        for child in layer:

child = psd[0][0]


The iteration order is from background to foreground, which is reversed from version prior to 1.7.x. Use reversed(list(psd)) to iterate from foreground to background.

The opened file can be saved:'output.psd')

Working with Layers

There are various layer kinds in Photoshop.

The most basic layer type is PixelLayer:

layer.kind == 'pixel'

Some of the layer attributes are editable, such as a layer name: = 'Updated layer 1'


Currently, the package does not support adding or removing of a layer.

Group has internal layers:

for layer in group:

first_layer = group[0]

TypeLayer is a layer with texts:


ShapeLayer draws a vector shape, and the shape information is stored in vector_mask and origination property. Other layers can also have shape information as a mask:

for shape in layer.origination:

SmartObjectLayer embeds or links an external file for non-destructive editing. The file content is accessible via smart_object property:

import io
if layer.smart_object.filetype in ('jpg', 'png'):
    image =

SolidColorFill, PatternFill, and GradientFill are fill layers that paint the entire region if there is no associated mask. Sub-classes of AdjustmentLayer represents layer adjustment applied to the composed image. See Adjustment layers.

Exporting data to PIL

Export the entire document as PIL.Image:

image = psd.compose()'exported.png')

Note that above compose() might return None if the PSD document has no visible pixel.

Export a single layer including masks and clipping layers:

image = layer.compose()

Export layer, mask, or clipping layers separately without composition:

image = layer.topil()
mask = layer.mask.topil()

from psd_tools import compose
clip_image = compose(layer.clip_layers)