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 PSD 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.composite()'exported.png')

Export a single layer including masks and clipping layers:

image = layer.composite()

Export layer and mask separately without composition:

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

To composite specific layers, such as layers except for texts, use layer_filter option:

image = psd.composite(
    layer_filter=lambda layer: layer.is_visible() and layer.kind != 'type')

Note that most of the layer effects and adjustment layers are not supported. The compositing result may look different from Photoshop.

Exporting data to NumPy

PSDImage or layers can be exported to NumPy array by numpy() method:

image = psd.numpy()
layer_image = layer.numpy()