importing psd with psd tools (en)

Importing PSD files (Adobe Photoshop) using psd-tools

Adobe Photoshop saves projects in the PSD format. Most command-line image converters render PSD files with a white background, discarding transparency. psd-tools — a Python library — correctly composites all layers with full alpha channel support, producing a proper transparent PNG.

Requirements

• Python 3.8 or newer
• psd-tools library — install it once with pip:

pip install psd-tools

Converter script

Save this script anywhere on your system (for example, psd_to_png.py):

#!/usr/bin/env python3
import sys
from psd_tools import PSDImage
PSDImage.open(sys.argv[1]).composite().save(sys.argv[2])

It takes two arguments: the path to the source PSD file and the path for the output PNG file.

Importality configuration

In Godot, open Project Settings → General → Advanced Settings → Importality and find the Command Building Rules for Custom Image Loader setting. Add a rule for the psd extension.

Windows:

psd: python C:\path\to\psd_to_png.py {in_path_b} {out_path_b}

Linux / macOS:

psd: python /path/to/psd_to_png.py {in_path} {out_path}

You may need to use python3 instead of python. You may also need to install the library explicitly:

python -m pip install psd-tools

Correct the path to the script to match your system. After saving the settings, restart the plugin so that it picks up the new extension.

Before using the rule in the plugin, test the command in a terminal:

python3 /path/to/psd_to_png.py /path/to/test.psd /tmp/test_out.png

Check that test_out.png has a transparent background.

Note: The "Background" layer

In Photoshop, the special locked layer called Background (the bottom-most layer, created by default in new documents) is inherently opaque white. psd-tools renders it correctly — as opaque — because that is what it is by design.

To get a transparent result, convert it to a regular layer in Photoshop before saving: double-click the Background layer → Layer from Background.

Standalone usage (without Python)

If you prefer not to install Python on the machine running Godot, you can create a self-contained executable using PyInstaller:

pip install pyinstaller
pyinstaller --onefile psd_to_png.py

The resulting binary in the dist/ folder requires no Python installation. Point the command building rule to it instead of calling python.