Aspose.PSD FOSS for Python

Aspose.PSD FOSS for Python is a free, open-source, pure-Python library for reading, inspecting and saving Adobe Photoshop .psd/.psb files without rendering. It runs on Python 3.7+ and depends only on the standard library. The library supports reading of document metadata, layers, channel information, blend modes, masks, image resources and image-data structures (RLE and ZIP compression).

Navigation

• At a Glance
• Key Capabilities
• Installation
• Dependencies
• Quick Start
• Additional Examples
• API Reference
• Documentation & Resources
• Scope and Limitations
• Development and Testing
• License

At a Glance

Key Capabilities

• Document inspection – PsdImage exposes width, height, channels, bits_per_channel, color_mode, version, is_psb, layer_count, resource_count, compression, image_data_kind, etc.
• Layer model – Layer provides name, bounds, top/left/bottom/right, width, height, opacity, is_visible, clipping, blend_mode_key, channels_count, channel_information. Mutations (name, visibility, opacity, blend mode, bounds) are tracked and saved preserving raw bytes when possible.
• Blend modes – BlendMode enum and LayerBlendModeMapper map between 4-character PSD keys and enum values.
• Channel information – ChannelInformation represents per-channel compression, length and identifier; read-only, raises NotSupportedException on write.
• Mask & blending ranges – LayerMaskDataShort, LayerBlendingRangesData expose raw length and basic properties; mutations are not supported.
• Image resources – ImageResourcesSection parses unknown resources, preserving raw payloads; UnknownResource offers resource_id, name, data. Helper classes (ResourceBlock, PreservedResourceBlock) provide a public surface.
• Image data parsing – ImageData parses RLE and ZIP structures without pixel decoding, exposing structure.kind, row_length_field_size, row_byte_counts, compressed_payload_length, uses_prediction.
• Byte-exact round-trip – PsdImage.save preserves all unmodified sections, enabling lossless save-load cycles.
• Non-seekable stream support – loading works with streams that do not support seeking.

Installation

pip install aspose-psd-foss

Requires Python 3.7 or later.

Dependencies

Required

• Python standard library only (no external packages).

Native / System

• None.

Development

• pytest ≥ 7.0.0 – test runner.
• pytest-cov ≥ 4.0.0 – coverage reporting.

Quick Start

from aspose_psd_foss.psdimage import PsdImage

# Load a PSD file
with PsdImage.load("example.psd") as img:
    print(f"Size: {img.width}x{img.height}")
    print(f"Layers: {len(img.layers)}")
    first = img.layers[0]
    print(f"First layer name: {first.name}")
    print(f"Blend mode: {first.blend_mode_key}")

    # Change visibility and save
    first.is_visible = not first.is_visible
    img.save("modified.psd")

Additional Examples

Enumerate layers and bounds

from aspose_psd_foss.psdimage import PsdImage

with PsdImage.load("sample.psd") as img:
    for idx, layer in enumerate(img.layers):
        print(f"{idx}: {layer.name} – {layer.bounds}")

Change layer blend mode

from aspose_psd_foss.psdimage import PsdImage
from aspose_psd_foss.layers.blendmode import BlendMode

with PsdImage.load("sample.psd") as img:
    img.layers[1].blend_mode_key = BlendMode.MULTIPLY
    img.save("blend_changed.psd")

Inspect image resources

from aspose_psd_foss.psdimage import PsdImage
from aspose_psd_foss.resources.imageresourceids import ImageResourceIds

with PsdImage.load("sample.psd") as img:
    for res in img.image_resources:
        if res.resource_id == ImageResourceIds.GLOBAL_ANGLE:
            print("Global angle resource found")

Verify byte-exact round-trip

with open(input_path, "rb") as f:
    input_bytes = f.read()

    input_stream = io.BytesIO(input_bytes)
    original_position = input_stream.tell()
    image = Image.load(input_stream)  # type: PsdImage

    print("Aspose.PSD Stream Sample")
    print(f"Input: {input_path}")
    print(f"Output: {output_path}")
    print(f"InputBytes: {input_byte_count}")
    print(f"OriginalStreamPosition: {original_position}")
    print(f"StreamPositionAfterLoad: {current_position}")

    output_stream = io.BytesIO()
    image.save(output_stream)
    output_bytes = output_stream.getvalue()
    with open(output_path, "wb") as f:
        f.write(output_bytes)

API Reference

The public entry point is the aspose_psd_foss package.

</details>  

## Documentation & Resources  

- **[Getting Started Guide](https://products.aspose.org/psd/python/)** – Overview of loading, inspection and saving.  
- **[API Reference](https://reference.aspose.org/psd/python/)** – Full browsable documentation of public types.  
- **[Knowledge Base](https://kb.aspose.org/psd/python/)** – FAQs, troubleshooting and how-to articles.  
- **[GitHub Repository](https://github.com/aspose-psd-foss/Aspose.PSD-FOSS-for-Python)** – Source code, issue tracker and contribution guide.  

## Scope and Limitations  

- **Supported formats** – Only Photoshop `.psd` (≤ 30 000 px) and `.psb` (≤ 300 000 px) containers are read. Other Photoshop-related formats (e.g., `.psd` with 16-bit or 32-bit per channel beyond supported bit depths) are not parsed.  
- **No pixel rendering** – The library provides metadata and structural access; actual pixel rasterisation is out of scope.  
- **Read-only mask and blending-range data** – Modifying mask data or blending ranges throws `NotSupportedException`.  
- **Limited color-mode support** – Indexed palette, RGB and CMYK payloads are parsed; other modes (Bitmap, Grayscale, Multichannel, Duotone, Lab) are treated as raw preserved data.  
- **Compression** – Supports RAW, RLE and ZIP (with/without prediction) image data structures; other compression schemes are not implemented.  

## Development and Testing  

```bash
# Install development dependencies and the package in editable mode
pip install -e ".[dev]"

# Run the full test suite
pytest -o python_files="*tests.py"