{"id":7518,"library":"psd-tools","title":"psd-tools","description":"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.","status":"active","version":"1.15.0.post1","language":"en","source_language":"en","source_url":"https://github.com/psd-tools/psd-tools","tags":["photoshop","psd","image processing","graphics","design","adobe"],"install":[{"cmd":"pip install psd-tools","lang":"bash","label":"Basic installation"},{"cmd":"pip install 'psd-tools[composite]'","lang":"bash","label":"With advanced compositing features"}],"dependencies":[{"reason":"Recommended for working with PSD image and layer data, including exporting to PNG and other processing. Required for image extraction from 32-bit PSD files.","package":"Pillow","optional":false},{"reason":"Required for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).","package":"aggdraw","optional":true},{"reason":"Required for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).","package":"scipy","optional":true},{"reason":"Required for advanced compositing features such as vector shape/stroke rendering, gradient/pattern fills, and layer effects rendering (part of the `composite` extra).","package":"scikit-image","optional":true}],"imports":[{"symbol":"PSDImage","correct":"from psd_tools import PSDImage"}],"quickstart":{"code":"import os\nfrom psd_tools import PSDImage\n\n# Create a dummy PSD for demonstration if it doesn't exist\ndummy_psd_path = 'example.psd'\nif not os.path.exists(dummy_psd_path):\n    # In a real scenario, you'd have an actual PSD file\n    # For this example, we'll just demonstrate the API calls.\n    # Creating a valid PSD requires more complex operations\n    # than a simple placeholder here.\n    print(f\"Please create a dummy '{dummy_psd_path}' file to run this quickstart.\")\n    print(\"Example: a small Photoshop file with a few layers.\")\nelse:\n    psd = PSDImage.open(dummy_psd_path)\n\n    # Print basic info\n    print(f\"Opened PSD: {psd}\")\n\n    # Composite the entire PSD and save as PNG\n    composite_image = psd.composite()\n    composite_image.save('example.png')\n    print(f\"Saved composite image to example.png\")\n\n    # Iterate through layers and save each as a separate PNG\n    for i, layer in enumerate(psd):\n        print(f\"Layer {i}: {layer.name} (Type: {layer.kind})\")\n        if layer.is_pixel_layer() and layer.visible:\n            layer_image = layer.composite()\n            if layer_image:\n                layer_image.save(f'{layer.name.replace(\" \", \"_\")}.png')\n                print(f\"Saved layer '{layer.name}' to {layer.name.replace(\" \", \"_\")}.png\")","lang":"python","description":"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."},"warnings":[{"fix":"If using advanced features, install with `pip install 'psd-tools[composite]'` or install dependencies individually: `pip install psd-tools aggdraw scipy scikit-image`.","message":"As 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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Use methods like `psdimage.create_pixel_layer(image, name=\"Layer 1\")` for layer creation, ensuring a `PSDImage` context.","message":"In 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.","severity":"breaking","affected_versions":">=1.11.0"},{"fix":"Replace calls to `compose()` with `composite()`.","message":"The `compose` module was dropped in v1.10. Users should migrate to using the `composite` method for image composition.","severity":"breaking","affected_versions":">=1.10.0"},{"fix":"To iterate from foreground to background (like older versions or Photoshop's layer panel), use `reversed(psd_image_object)`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.7.0"},{"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.","message":"Compositing results from `psd-tools` may differ from Photoshop's rendering due to limited support for many layer effects and adjustment layers.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Extracting images from 32-bit PSD files requires the Pillow library to be built with LITTLECMS or LITTLECMS2 support.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the optional dependencies: `pip install 'psd-tools[composite]'`","cause":"Attempting to use advanced compositing features (like vector masks, gradients, or layer effects) without installing the `composite` extra dependencies.","error":"ImportError: Advanced compositing features require optional dependencies. Install with: pip install 'psd-tools[composite]'"},{"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.","cause":"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.","error":"KeyError: 'FillColor' (or similar KeyError for layer properties like 'FontSize', 'SmartObject', etc.)"},{"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.","cause":"This error typically indicates a corrupted PSD file or an issue during the decompression process of image data within the PSD.","error":"Error -3 while decompressing data: incorrect data check"},{"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.","cause":"`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.","error":"Image conversion to PIL fails or produces unexpected results for certain layer types (e.g., 'type' layers, 'shape' layers)"}]}