Registry / data / psd-tools

psd-tools

JSON →
library1.17.2pypypi✓ verified 87d ago

psd-tools is a Python package designed for working with Adobe Photoshop PSD and PSB files, enabling reading, writing, and manipulation of layer data and compositions. The current version is 1.15.0.post1, and it maintains an active release cadence with frequent updates and improvements. It provides functionalities for low-level file structure access, raw layer image export, and limited layer composition.

pip install psd-tools
INSTALL
IMPORT
SIG · PSD-TOOLS
P
psd-tools
datapythonv1.17.2
Install
8.6s avg
Import
769ms
Disk
308MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.17.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
4/8 runs
✓ 7.96s
py 3.11
4/8 runs
✓ 7.6s
py 3.12
4/8 runs
✓ 7.49s
py 3.13
4/8 runs
✓ 7.46s
py 3.9
✕ build_error
✓ 12.48s
308MB installed
● package 308MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PSDImage
from psd_tools import PSDImage

This quickstart demonstrates how to open a PSD file, composite the entire image, and then iterate through its layers, saving each visible pixel layer as a separate PNG. Ensure you have an 'example.psd' file available for the code to run successfully.

import os from psd_tools import PSDImage # Create a dummy PSD for demonstration if it doesn't exist dummy_psd_path = 'example.psd' if not os.path.exists(dummy_psd_path): # In a real scenario, you'd have an actual PSD file # For this example, we'll just demonstrate the API calls. # Creating a valid PSD requires more complex operations # than a simple placeholder here. print(f"Please create a dummy '{dummy_psd_path}' file to run this quickstart.") print("Example: a small Photoshop file with a few layers.") else: psd = PSDImage.open(dummy_psd_path) # Print basic info print(f"Opened PSD: {psd}") # Composite the entire PSD and save as PNG composite_image = psd.composite() composite_image.save('example.png') print(f"Saved composite image to example.png") # Iterate through layers and save each as a separate PNG for i, layer in enumerate(psd): print(f"Layer {i}: {layer.name} (Type: {layer.kind})") if layer.is_pixel_layer() and layer.visible: layer_image = layer.composite() if layer_image: layer_image.save(f'{layer.name.replace(" ", "_")}.png') print(f"Saved layer '{layer.name}' to {layer.name.replace(" ", "_")}.png")
Debug
Known issues
breakingAs of v1.12, advanced compositing features (vector shapes, gradients, layer effects) require optional dependencies ('aggdraw', 'scipy', 'scikit-image') to be explicitly installed via `pip install 'psd-tools[composite]'`. Basic compositing with NumPy still works without them.
fix
If using advanced features, install with `pip install 'psd-tools[composite]'` or install dependencies individually: `pip install psd-tools aggdraw scipy scikit-image`.
affects: >=1.12.0
breakingIn v1.11, layer creation APIs changed. Layers now require a valid `PSDImage` object and cannot be created as 'orphaned' layers or shared between multiple container objects.
fix
Use methods like `psdimage.create_pixel_layer(image, name="Layer 1")` for layer creation, ensuring a `PSDImage` context.
affects: >=1.11.0
breakingThe `compose` module was dropped in v1.10. Users should migrate to using the `composite` method for image composition.
fix
Replace calls to `compose()` with `composite()`.
affects: >=1.10.0
gotchaThe iteration order for layers in a `PSDImage` object is from background to foreground by default. This is reversed from versions prior to 1.7.x.
fix
To iterate from foreground to background (like older versions or Photoshop's layer panel), use `reversed(psd_image_object)`.
affects: >=1.7.0
gotchaCompositing results from `psd-tools` may differ from Photoshop's rendering due to limited support for many layer effects and adjustment layers.
fix
Be aware of this limitation; for exact Photoshop rendering, you may need to rely on Photoshop itself or check for updates to `psd-tools` that expand rendering support.
affects: All versions
gotchaExtracting images from 32-bit PSD files requires the Pillow library to be built with LITTLECMS or LITTLECMS2 support.
fix
Ensure your Pillow installation has LITTLECMS/LITTLECMS2 support. This often requires installing development headers before installing Pillow, or using pre-built wheels that include it.
affects: All versions
Errors
Common errors & fixes
ImportError: Advanced compositing features require optional dependencies. Install with: pip install 'psd-tools[composite]'
Attempting to use advanced compositing features (like vector masks, gradients, or layer effects) without installing the `composite` extra dependencies.
fix
Install the optional dependencies: `pip install 'psd-tools[composite]'`
KeyError: 'FillColor' (or similar KeyError for layer properties like 'FontSize', 'SmartObject', etc.)
The `psd-tools` library might not fully support parsing specific types of layer data or smart object properties, leading to missing keys when trying to access them.
fix
Consult the `psd-tools` documentation or GitHub issues to check for specific layer type support. If unsupported, you may need to access lower-level PSD structures or consider alternative methods for these specific properties.
Error -3 while decompressing data: incorrect data check
This error typically indicates a corrupted PSD file or an issue during the decompression process of image data within the PSD.
fix
Verify the integrity of the PSD file. Try opening it in Photoshop to see if it's recoverable. If not, you might need a backup of the PSD or specialized PSD repair tools.
Image conversion to PIL fails or produces unexpected results for certain layer types (e.g., 'type' layers, 'shape' layers)
`psd-tools` has limited support for rendering certain complex layer types (like type layers, shape layers, smart objects) directly into pixel data without Photoshop's engine.
fix
For these layer types, `layer.composite()` might return `None` or an incomplete image. If direct pixel access is needed, ensure the PSD is saved with 'Maximize Compatibility' in Photoshop, which embeds a composite image.
Upgrade
Version history
1.17.2latest on PyPI · released Jun 4, 2026
Audit
Dependencies
PillowrequiredRecommended for working with PSD image and layer data, including exporting to PNG and other processing. Required for image extraction from 32-bit PSD files.
aggdrawoptionalRequired for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).
scipyoptionalRequired for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).
scikit-imageoptionalRequired for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).
Agent activity
93 hits · last 30 days
node
90
Resources