Dedicated Lua script to re-import PSD files that were previously exported
using Export as psd.lua (Aseprite → PSD) back into Aseprite.
| Feature | Description |
|---|---|
| RGB / RGBA (8 bpc) Support | Recognizes both 3-channel (RGB) and 4-channel (RGBA) formats; automatically generates opaque alpha if missing |
| Perfect Group Structure Restoration | Interprets PSD lsct (Section Divider) Types 0-3 → Converts to Aseprite folders with Layer.isGroup = true |
| PackBits RLE Decompression | Implements only the compression used by the export script, reducing complexity while increasing speed |
| UTF-8 Safe Name Handling | Converts luni (UTF-16BE) layer names → UTF-8, automatically replaces invalid bytes to prevent crashes |
| CLI & GUI Support | Both Aseprite UI dialog and aseprite -b -script ... --filename=… command-line usage |
| Automatic Debug Logging | Generates PSD Import Debug Log.txt in the same folder for layer tree and error tracking |
- Aseprite ≥ 1.2.10-beta3 (API v1 or higher)
- Lua 5.3 (built-in)
- Tested on: Windows 10 / macOS 13 / Ubuntu 22.04
- Copy
import from psd.luato:
Aseprite ▶ File ▶ Scripts ▶ Open Scripts Folder - Restart Aseprite or use
Scripts ▶ Rescan Scripts Folder - If you see
File ▶ Scripts ▶ import from psdin the menu, installation is complete
- Select Scripts ▶ import from psd
- Choose your
.psdfile → Click Import - The imported sprite will open in a new tab
| Item | Status |
|---|---|
| 8 bpc Bit Depth | ✔ |
| RGB Color Mode | ✔ |
| Alpha Channel (-1) | ✔ (Auto-opaque if missing) |
| Group (Folder) Hierarchy | ✔ |
| Layer Masks | ✖ Ignored |
| Adjustment/Text Layers | ✖ Ignored (not rasterized) |
| 16/32 bpc, CMYK, etc. | ✖ Not supported |
-
Large PSD files (hundreds of MB): Memory usage may increase significantly when PackBits compression is absent or when decompressed data is very large.
-
Surrogate pairs (U+10000+): Rarely used in PSD spec, but will be replaced with "?" if encountered.
Issues and Pull Requests are welcome! 📬
Please attach sample PSD files for bug reproduction or Sentry logs when reporting issues.
MIT License — Feel free to use, modify, and distribute while maintaining the license text and copyright notice.
- Aseprite API Documentation
- Adobe Photoshop File Formats Specification
- Export as psd.lua (companion export script)
- LayerVault: Anatomy of a PSD