psdparse

Pure C++17 PSD (Photoshop) reader/writer library, with pybind11-based Python bindings.

Lazy I/O: PSD pixel data is not copied into memory at parse time. Only the structural metadata (a few hundred KB even for large files) is read upfront; layer pixels are paged in on demand via mmap or stream callbacks.
Round-trip save: load(p) -> save(q) produces a byte-identical PSD file.
Edit & save: add / delete / reorder / duplicate layers, copy layers between files, replace layer & mask pixels, edit parameters / names / masks / fill opacity, edit layer-effect (lfx2) values and text content, or build a PSD from scratch — all with byte-exact re-serialization of the parts you touch (unedited layers stay byte-identical).
Python wrapper: import psdparse → PSDFile.load(path) / layer_image(i) / merged_image() / save(path) plus the editing API.

The library was extracted from the psdfile kirikiri plugin in 2026. psdfile now consumes this library as a submodule.

Architecture (quick read)

See docs/ARCHITECTURE.md for full details.

IteratorBase (psdbase.h, pure virtual — parser only sees this)
├── MemoryReader   (psdparse.h)  ... mmap / contiguous buffer
└── StreamReader   (psdparse.h)  ... arbitrary seekable stream
    └── Source (pure virtual; subclass per backend)
        ├── IStreamSource              ... std::istream
        └── (your custom Source)       ... e.g. iTJSBinaryStream wrapper

WriterBase (psdwrite.h, pure virtual — symmetric to IteratorBase)
└── FileWriter (FILE*)

psd::PSDFile::load(const char *path) mmaps a local file. loadFromStream(std::istream&) / loadFromReader(IteratorBase&) accept arbitrary I/O. save(const char *path) writes the loaded data back as PSD.

All public path arguments are UTF-8 (char *). On Win32, conversion to UTF-16 happens internally via psd::utf8ToWide (inline in psdbase.h).

Install (Python)

pip install psdparse          # once published to PyPI

Build from source — needs only a C++17 compiler + CMake 3.16+, no vcpkg:

pip install .                 # or:  pip wheel . -w dist

zlib is taken from the system if present, otherwise fetched from source by CMake (FetchContent), so no package manager is required. Packaging uses scikit-build-core; cross-platform wheels are built in CI (.github/workflows/wheels.yml, cibuildwheel).

Build (C++ library / CLI)

Requires CMake 3.16+ and a C++17 compiler. vcpkg is no longer needed.

# C++ library + CLI (static CRT)
cmake --preset x64-windows
cmake --build --preset x64-windows --config Release

# C++ library + Python module (dynamic CRT, matches CPython)
cmake --preset x64-windows-python
cmake --build --preset x64-windows-python --config Release

Makefile is a thin wrapper:

make PRESET=x64-windows prebuild build
make PRESET=x64-windows-python prebuild build

Build artifacts:

build/x64-windows/psdparse/Release/psdparse_cli.exe
build/x64-windows-python/python/Release/psdparse.cp312-win_amd64.pyd

Only dependency: zlib (system, or auto-fetched from source).

Python API

import psdparse

p = psdparse.PSDFile()
p.load(r"path/to/file.psd")   # mmap-backed

print(p.header.width, p.header.height, len(p.layers))
for layer in p.layers:
    print(layer.name_unicode, layer.blend_mode.name, layer.opacity)

bgra = p.merged_image()                # bytes, BGRA, 4*W*H
layer_bgra = p.layer_image(0, "masked") # bytes, BGRA, 4*w*h

p.save(r"out.psd")              # byte-identical round-trip

Editing (8-bit RGB), re-serialized on save — unedited layers stay byte-identical:

p.layers[0].opacity = 128                       # parameters
p.layers[0].name_unicode = "背景"               # rename
p.delete_layer(3); p.move_layer(1, 4)           # structure
p.set_layer_pixels(0, bgra_bytes, w, h)         # replace pixels
p.set_layer_mask_pixels(0, gray, 0, 0, w, h)    # mask pixels + geometry
p.set_effects(0, {"masterFXSwitch": False})     # layer-effect values
p.set_text(2, "新しいテキスト")                 # text content
p.save(r"edited.psd")

q = psdparse.PSDFile()                           # or build one from scratch
q.create_blank(1024, 768)
q.add_layer("bg", 0, 0, bgra_bytes, 1024, 768)
q.save(r"new.psd")

Full API reference: docs/PYTHON_API.md.

PSD feature coverage

What psdparse can and cannot read and edit, at a glance: docs/SUPPORT.md (対応状況マトリクス).

Tests

Tests live under tests/ and use pytest. They need sample PSDs placed at the repo root or tests/data/ (not committed — listed in .gitignore); without them the tests skip rather than fail.

# after building the Python module (pip install . / preset x64-windows-python):
python -m pytest -v

tools/psd_export.py

python tools/psd_export.py input.psd [--out-dir DIR] [--mode masked|image|mask]

Outputs layers.json (full layer metadata), merged.png (composite), and per-layer PNGs.

License

MIT — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

psdparse-0.7.0.tar.gz (127.3 kB view details)

Uploaded Aug 2, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

psdparse-0.7.0-cp314-cp314t-win_amd64.whl (290.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.14tWindows x86-64

psdparse-0.7.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (314.2 kB view details)

Uploaded Aug 2, 2026 CPython 3.14tmanylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp314-cp314t-macosx_11_0_arm64.whl (261.2 kB view details)

Uploaded Aug 2, 2026 CPython 3.14tmacOS 11.0+ ARM64

psdparse-0.7.0-cp314-cp314t-macosx_10_15_x86_64.whl (290.0 kB view details)

Uploaded Aug 2, 2026 CPython 3.14tmacOS 10.15+ x86-64

psdparse-0.7.0-cp314-cp314-win_amd64.whl (282.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.14Windows x86-64

psdparse-0.7.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (313.4 kB view details)

Uploaded Aug 2, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp314-cp314-macosx_11_0_arm64.whl (247.6 kB view details)

Uploaded Aug 2, 2026 CPython 3.14macOS 11.0+ ARM64

psdparse-0.7.0-cp314-cp314-macosx_10_15_x86_64.whl (279.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.14macOS 10.15+ x86-64

psdparse-0.7.0-cp313-cp313t-win_amd64.whl (282.1 kB view details)

Uploaded Aug 2, 2026 CPython 3.13tWindows x86-64

psdparse-0.7.0-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (314.6 kB view details)

Uploaded Aug 2, 2026 CPython 3.13tmanylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp313-cp313t-macosx_11_0_arm64.whl (261.0 kB view details)

Uploaded Aug 2, 2026 CPython 3.13tmacOS 11.0+ ARM64

psdparse-0.7.0-cp313-cp313t-macosx_10_13_x86_64.whl (289.9 kB view details)

Uploaded Aug 2, 2026 CPython 3.13tmacOS 10.13+ x86-64

psdparse-0.7.0-cp313-cp313-win_amd64.whl (274.4 kB view details)

Uploaded Aug 2, 2026 CPython 3.13Windows x86-64

psdparse-0.7.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (313.1 kB view details)

Uploaded Aug 2, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp313-cp313-macosx_11_0_arm64.whl (247.1 kB view details)

Uploaded Aug 2, 2026 CPython 3.13macOS 11.0+ ARM64

psdparse-0.7.0-cp313-cp313-macosx_10_13_x86_64.whl (279.5 kB view details)

Uploaded Aug 2, 2026 CPython 3.13macOS 10.13+ x86-64

psdparse-0.7.0-cp312-cp312-win_amd64.whl (274.4 kB view details)

Uploaded Aug 2, 2026 CPython 3.12Windows x86-64

psdparse-0.7.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (313.1 kB view details)

Uploaded Aug 2, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp312-cp312-macosx_11_0_arm64.whl (247.0 kB view details)

Uploaded Aug 2, 2026 CPython 3.12macOS 11.0+ ARM64

psdparse-0.7.0-cp312-cp312-macosx_10_13_x86_64.whl (279.5 kB view details)

Uploaded Aug 2, 2026 CPython 3.12macOS 10.13+ x86-64

psdparse-0.7.0-cp311-cp311-win_amd64.whl (271.8 kB view details)

Uploaded Aug 2, 2026 CPython 3.11Windows x86-64

psdparse-0.7.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (311.1 kB view details)

Uploaded Aug 2, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp311-cp311-macosx_11_0_arm64.whl (245.9 kB view details)

Uploaded Aug 2, 2026 CPython 3.11macOS 11.0+ ARM64

psdparse-0.7.0-cp311-cp311-macosx_10_13_x86_64.whl (276.2 kB view details)

Uploaded Aug 2, 2026 CPython 3.11macOS 10.13+ x86-64

psdparse-0.7.0-cp310-cp310-win_amd64.whl (269.4 kB view details)

Uploaded Aug 2, 2026 CPython 3.10Windows x86-64

psdparse-0.7.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (309.6 kB view details)

Uploaded Aug 2, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp310-cp310-macosx_11_0_arm64.whl (244.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.10macOS 11.0+ ARM64

psdparse-0.7.0-cp310-cp310-macosx_10_13_x86_64.whl (274.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.10macOS 10.13+ x86-64

psdparse-0.7.0-cp39-cp39-win_amd64.whl (269.4 kB view details)

Uploaded Aug 2, 2026 CPython 3.9Windows x86-64

psdparse-0.7.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (309.7 kB view details)

Uploaded Aug 2, 2026 CPython 3.9manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

psdparse-0.7.0-cp39-cp39-macosx_11_0_arm64.whl (244.8 kB view details)

Uploaded Aug 2, 2026 CPython 3.9macOS 11.0+ ARM64

psdparse-0.7.0-cp39-cp39-macosx_10_13_x86_64.whl (274.8 kB view details)

Uploaded Aug 2, 2026 CPython 3.9macOS 10.13+ x86-64

File details

Details for the file psdparse-0.7.0.tar.gz.

File metadata

Download URL: psdparse-0.7.0.tar.gz
Upload date: Aug 2, 2026
Size: 127.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for psdparse-0.7.0.tar.gz
Algorithm	Hash digest
SHA256	`880351030aae08914df39f60b8c639933d8e926ca186cdf9c5314774b0bf2c39`
MD5	`12cf6b1fd21a211ce8cb5567754bfd89`
BLAKE2b-256	`06300fffa6169f5e5e0001b6ce4dad4298316657acc692d3909755545b964721`

Algorithm	Hash digest
SHA256	`ef1b11ce86a33691364f7953ecc9f5b2cd318b431381730b3e205539c1715306`
MD5	`339d0e47c7c07a9d6903585d75f5e787`
BLAKE2b-256	`5678971e9a4db1cb7fe40bfc91c5432e85c4f2f19325dcd9245d9e0eaa085ad6`

Algorithm	Hash digest
SHA256	`c0cadc2add717c86a16c8806c8d8595c5c54c5c94003be2acc1073541850c912`
MD5	`69531b1091a34f2fa49024a492983dca`
BLAKE2b-256	`7e086e0df489b72a6f47a6338f08df1952fa2e6ca99c4e98f3d089271dae7c8c`

Algorithm	Hash digest
SHA256	`21375a1605bea24475d289b6649f5d1d847f6edfc7a2480f0aa30e182332f9a5`
MD5	`42a3e3bfac4fd097c5c982dacfb418a2`
BLAKE2b-256	`b0301758b3b9b093084ac35b4d3d6281eda0570820329521ebdb29d2194c7045`

Algorithm	Hash digest
SHA256	`09178c59e81f86d78daccea14d949f3d5daf85f5594d3c1b216a20d37adf2192`
MD5	`73d85202f1989454235cd8b36e65275e`
BLAKE2b-256	`44ce9f3453c59fda894d4086165106e87639c3f2a4a25ca3ab0d0d3a4ffc3e50`

Algorithm	Hash digest
SHA256	`4a7f1f5b7d3089f0907ad41a1bfc9b8ecbfdbbd7c782aab958e27d9deea461c2`
MD5	`5b4f74c0dae26179b168c910119140c5`
BLAKE2b-256	`b5fac605c52e0b7cb26bfaf7582fa1afb56d9fef012ebbd6b86fb616cafcc55e`

Algorithm	Hash digest
SHA256	`ad07399d9df57d7a9e088141ba81831fba6120b1647edf123e493acbc8062aa8`
MD5	`ba1ed537867ff465636c9511d2d1655a`
BLAKE2b-256	`1e788ae02876cd49ce32d3c6e0889333204ac41660bed851c4c26de114124a7d`

Algorithm	Hash digest
SHA256	`4700893cdc0f4070fcfb2410f56ac3d3a8f1320e823c26f0c0150e6be4f1e4fb`
MD5	`f1be86e47433d9cb8739156f1a679086`
BLAKE2b-256	`dbc3b4036425be79c8b2c739a96a189df525d7371ab52a744f2e333a90ba1997`

Algorithm	Hash digest
SHA256	`8c81be3dbfe7bfc95d8b45f9ea5d2bb501aba851a9b071b23e247d17a7dac934`
MD5	`41761037cb1007a3ae2bf884218a2ccf`
BLAKE2b-256	`b44c8995b8bdfd605846091fcaee86750bfdb2ffd140c835609cdbf50db6bf93`

Algorithm	Hash digest
SHA256	`34ce96ec69a1dc430548b3b776cf79349c276abdf2af568c2756060370d8f6b8`
MD5	`222c3a803d654270abd20920281ad791`
BLAKE2b-256	`b3543f85e2a97fa9ff090e42da38f826a0e62cac15670812ac78e4c60411e410`

Algorithm	Hash digest
SHA256	`89c2ba2821009b94093115920bac740728161954fc997bee4ac14c579e94f09a`
MD5	`427911900b26f915f37dc34771ea42c8`
BLAKE2b-256	`7f6436774c587a0d6097d1589210f27a769bed27627cb684b6f286f0c34d38a6`

Algorithm	Hash digest
SHA256	`689bbf1ab2b53e24107a6552a589391a39ebd3114d9aa87c7ebf71432ffaa1f1`
MD5	`475409f79152aed1b085db88b1bf0eba`
BLAKE2b-256	`690ed2e3464a1336afa9fcb3c1f1482f58d03ac99f873a97b1930d693c9ad443`

Algorithm	Hash digest
SHA256	`738637dd0fdf0e52de51548b8310d4dbd567cc240aadd87c94999f11219a63ad`
MD5	`2b7b5ff6c6c79dca87df60b90f8bc498`
BLAKE2b-256	`6cd4f8cde7e562050f5c27acfde17a8804b1e3dd101a3dc2928842cbba045d32`

Algorithm	Hash digest
SHA256	`ec48673af50c3ad93a7bf5f37bccb0946881b4b1ab1c837ed51f4009a4b48c94`
MD5	`a28cbfa11f8459dae7ea5a502c05df03`
BLAKE2b-256	`0d89443735166ffe7b872fe0dddde4ba5b499b5f69dadf5905e1b9376a297953`

Algorithm	Hash digest
SHA256	`2a601660975648c16d5c00e6b556648d68245a527180cc14f7a283e3933e12cf`
MD5	`88cb2812cde9dcbf69445db44fd17d25`
BLAKE2b-256	`ef1eeee916f8c505e5c03103747403776c3db5b81f40cf8a255231605f503415`

Algorithm	Hash digest
SHA256	`ae483150661d367fa3d422f55447522aa76f0a07d65a5146829d62d1f00c0b64`
MD5	`07cd0da2ef562de8cb820bad120367b2`
BLAKE2b-256	`f9d70d176d130ecd7620ea26fedff71d978f660a96a267410b164a4225076990`

Algorithm	Hash digest
SHA256	`311a5323c0cc1b921efa80b97895afeae053da8d60b82a75a3f7c1af80b87866`
MD5	`644a97b85d21ea477131840dc3787a17`
BLAKE2b-256	`75acbef621e1f370e8fe3ce9739576885c3a3711236bc5aa4eae672d99bad2ee`

Algorithm	Hash digest
SHA256	`0878b6e803e7e5418b8d06c5f66a7d224f4665686deeb944a577076fa8010cc1`
MD5	`52668232ec9c3451d65c9140f79abcdf`
BLAKE2b-256	`ba8a49633b4bafe8d11d9dd10ed7d6fd2fe121a1939c7274f3a7aeaa9da32793`

Algorithm	Hash digest
SHA256	`b8ecca72c19132e19328eaf3839e2447824c040dda80bcf7951a1c78ba717ffd`
MD5	`8f63102a7e2443f7eecb750bb8926786`
BLAKE2b-256	`a8586cb4367442fe5c727979dc5d21991b17206a61e55d3fd8818d567233b41f`

Algorithm	Hash digest
SHA256	`3e71f386301218bfe33c18af61b8ada40ac6e2f91a7b24607c2a9ad8f8c80d55`
MD5	`b4be73f0e09dd247e5a5f3018fe1fb48`
BLAKE2b-256	`2e939e6b1fff5db905522bb2e6a70faf98a7eee6fcf0a9a14f8230b12d76bc8f`

Algorithm	Hash digest
SHA256	`3d2a3b7fef67e6edb7dd1a4cd7812e4a74c3914fd395090904fdcd7d2fc7ee86`
MD5	`0bbe1398da8eb2a4a1c1893de3cffe43`
BLAKE2b-256	`5843c7ad4e6aef1c316bcabce2b015672487619612623f8b3ed4c6dae2d926f3`

psdparse 0.7.0

psdparse

Architecture (quick read)

Install (Python)

Build (C++ library / CLI)

Python API

PSD feature coverage

Tests

tools/psd_export.py

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Algorithm	Hash digest
SHA256	`9e6c8a0ca99b081938dee69ed37f43fbe02da4cc466c8d10cd9f709b04062a72`
MD5	`e27e3740674700db0d1cb2d13d013d4e`
BLAKE2b-256	`d860f1cd5f980c36dfadc98ce0174b7d88d63b0026ecf68a45192eb7a25ae936`

Algorithm	Hash digest
SHA256	`e4b3eaab91e09e54492c2f159b35ed215b49dbf1f499192060626103769d3b86`
MD5	`614af244f6e451d4d8af7f8713077dc1`
BLAKE2b-256	`7b652bf1c183c422a233d0866a50c7a739af96901b5223679349ea32999db9fa`

Algorithm	Hash digest
SHA256	`4420952576fb178b8b819f4a3d134072de05f3f3e6415f44862756d95354dcc4`
MD5	`bd65e8f7bdfed82abcfe19f58f1f9f9b`
BLAKE2b-256	`06efd9db1f2b5427b8b66dab0273c4418e07e72cc8e79356bd5c07ef858ed57d`

Algorithm	Hash digest
SHA256	`4cbbfac79f87175174e2c5e3c17f0649683250b73438a3d03dc58524567f63ff`
MD5	`56ae07f53102210cd825cbf9e64a5c31`
BLAKE2b-256	`b9183a5c89ae176bd4b5dac20ca113692ac336c99e3841ede9923b3163c10ab6`

Algorithm	Hash digest
SHA256	`115c15d8c0877de9f085f1169728c57114476393e7c0f10a5b5c87257be19068`
MD5	`cf9d9a9f954660d97b48de5e2588a28f`
BLAKE2b-256	`fe91674973949c80df058436908837471ff33bb3d92b1e49df3ac864ce89d4e5`

Algorithm	Hash digest
SHA256	`f1bd5c7b774b589b8df832710f669aacb48400093b7f27dd110b8269e896886f`
MD5	`75c9cf952bf85b7e7b3404d5f953db11`
BLAKE2b-256	`15e10cc4b7d8d02fc51c2b3ccfef0b7df44aed020aacf1c4451c529e2cc32a2d`

Algorithm	Hash digest
SHA256	`fa335b50e566d9f239c7ee68bced8f5fe09f21030c418b4b84c88fae1e9f726e`
MD5	`365e1306b05f03caa61d8d0c23bca020`
BLAKE2b-256	`19c2edb0bd47536a00afa74b0931662a9a5e7218df017610be0df0a02cb9272f`

Algorithm	Hash digest
SHA256	`b635c500df03d4c92310d6c3b9347cc97bb2217369170db1cadfc7b9ff5b3b7a`
MD5	`2ffe869a3eb503031bcea5c8647ac6eb`
BLAKE2b-256	`becbe724042b18876245b4ce30cff4de90c0fab86171c01e9645a7053050e77d`

Algorithm	Hash digest
SHA256	`493f671175a5f354d38c17581c89c94b8613713ef49582bf60074e48e239ac89`
MD5	`6d4f55ddaaa49412de42f92522bd8235`
BLAKE2b-256	`f967295c6f497a459ad37a1d8b96476697f39d2a50d9d544b416f365670c52eb`

Algorithm	Hash digest
SHA256	`044276b63b5a784e02e20c4523675e22ab2c26788671dea2c798da75ee7fb1d7`
MD5	`f07dd2ffffc4de0f03738e5f4dac1113`
BLAKE2b-256	`9e92c0b85189b7665a9a968d724a28abecf1d485cbe1f139b3ccb4d8bd4e4ae8`