How to Save and Export PSD Documents in Python

PsdImage.save is the single public entry point for writing a document back out — it accepts either a file path or an already-open writable stream. The low-level section writer that does the actual byte encoding is an internal implementation detail, not something you call directly.

Step-by-Step Guide

Step 1: Install the Package

git clone https://github.com/aspose-psd-foss/Aspose.PSD-FOSS-for-Python.git
cd Aspose.PSD-FOSS-for-Python
# No packaging manifest is published yet -- run from this folder,
# or add it to PYTHONPATH:
export PYTHONPATH=$PWD:$PYTHONPATH

Step 2: Import Required Classes

from aspose_psd_foss.psdimage import PsdImage

Step 3: Save to a File Path

image = PsdImage.load("input.psd")
image.layers[0].is_visible = False
image.save("output.psd")

Step 4: Save to an Open Stream

Passing a stream instead of a path leaves the stream open after saving — you control when to close it:

with open("output.psd", "wb") as stream:
    image.save(stream)

Step 5: Dispose the Image

image.dispose()

Common Issues and Fixes

RuntimeError: PsdImage has been disposed. when calling save. The image was already disposed (via dispose() or a with block that exited) before save was called. Call save before disposing.

PsdSaveException about a Pascal string length. A string value exceeds 255 bytes — see Handling PSD Core Exceptions and Troubleshooting.

No way to force a PSD or PSB container on save. There is no public API to choose the output container format — a save always mirrors whichever format (is_large_document / is_psb) the document was loaded with. If you need a different container format, there is no supported conversion path in this FOSS build.

Frequently Asked Questions

Does saving to a stream close the stream afterward?

No — when you pass a stream to save, the stream is left open afterward so you control its lifecycle (see Step 4). Saving to a file path, by contrast, opens and closes the file internally.

Can I call the internal section writer directly instead of `save`?

No — the section-level writer is an internal implementation detail invoked by PsdImage.save. There is no documented, supported way to write a document outside of calling save on a PsdImage instance.