psd-tools

psd-tools is a pure-Python library for working with Adobe Photoshop’s PSD and PSB file formats. It parses the low-level layer, mask, and resource structures defined in Adobe’s file specification and exposes them as a Pythonic object tree, letting you inspect layers, extract text and vector data, and render composited output without opening Photoshop itself.

Beyond parsing, psd-tools can composite pixel layers, fill layers, adjustment layers, and vector masks into final images using NumPy and PIL, making it useful for automated thumbnail generation, design-asset pipelines, and batch processing of PSD archives.

What You Get

• A full parser for the PSD/PSB low-level file structure, including layers, groups, masks, and image resources
• Layer image export to NumPy arrays or PIL images for individual layers or full-document composites
• Composition support for pixel layers, fill layers, adjustment layers (brightness/contrast, curves, levels, exposure), and vector masks
• An optional composite extra (aggdraw, scipy, scikit-image) for advanced vector shape, gradient, and layer-effect rendering
• Basic editing capabilities for layer names, groups, and pixel layers

Common Use Cases

• Generating PNG/JPEG thumbnails or previews from PSD design files in a build or CMS pipeline
• Extracting layer metadata and raster content for automated design-QA or asset-export tooling
• Batch-processing large archives of legacy PSD files to migrate assets to modern formats
• Building design-to-code tools that need programmatic access to layer positions, styles, and text

Under The Hood

Architecture: The library is layered around a low-level psd_tools.psd module that mirrors Adobe’s binary PSD/PSB specification (headers, image resources, tagged blocks, layer records) and a higher-level psd_tools.api module (PSDImage, Layer, Mask, SmartObject) that wraps the raw structures in an ergonomic, iterable Python tree; compositing flows from parsed layer records through numpy_io.py/pil_io.py converters into NumPy arrays or PIL images. Tech Stack: Pure Python 3.10+ with attrs for structured records, Pillow and numpy as core dependencies, and an optional composite extra (aggdraw, scipy, scikit-image) for vector-shape and gradient rendering; packaging uses setuptools with a small Cython extension for performance-sensitive decoding. Code Quality: The tests/ directory holds 46 files and roughly 490 test functions covering descriptors, engine data, tagged blocks, and full PSD fixture files, run via pytest/pytest-cov; the project also uses ruff and mypy per its dependency groups, and ships a py.typed marker for type-checked consumers. API Design: The PSDImage.open() entry point and iterable layer tree give a low-boilerplate, Pythonic API (for layer in psd: layer.composite()), though advanced compositing features require understanding PSD’s internal layer-effect model, which the docs surface through worked examples rather than a fully declarative API.