Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install psd-tools

How to install psd-tools

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install psd-tools
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
0.8.4Never BuiltWhy not?
0.2 Available View build log
Windows (64-bit)
Mac OS X (10.5+)
0.8.4Never BuiltWhy not?
0.2 Available View build log
0.8.4Never BuiltWhy not?
0.7 Available View build log
0.6 Failed View build log
0.5 Available View build log
0.2 Available View build log
0.1.4 Available View build log
Linux (32-bit)
0.8.4Never BuiltWhy not?
0.7 Available View build log
0.6 Available View build log
0.5 Available View build log
0.2 Available View build log
0.1.4 Available View build log
0.8.4Never BuiltWhy not?
0.7 Available View build log
0.6 Failed View build log
0.5 Available View build log
0.2 Available View build log
0.1.4 Available View build log
Linux (64-bit)
0.8.4Never BuiltWhy not?
0.7 Available View build log
0.6 Available View build log
0.5 Available View build log
0.2 Available View build log
0.1.4 Available View build log
0.8.4Never BuiltWhy not?
0.7 Available View build log
0.6 Failed View build log
0.5 Available View build log
0.2 Available View build log
0.1.4 Available View build log
0.8.4 Available View build log
MIT License
Depended by
Lastest release
version 0.8.4 on Sep 20th, 2013

psd-tools is a package for reading Adobe Photoshop PSD files (as described in specification) to Python data structures.



pip install psd-tools

There are also optional dependencies:


In order to extract images from 32bit PSD files PIL/Pillow must be built with LITTLECMS support.


Load an image:

>>> from psd_tools import PSDImage
>>> psd = PSDImage.load('my_image.psd')

Read image header:

>>> psd.header
PsdHeader(number_of_channels=3, height=200, width=100, depth=8, color_mode=RGB)

Access its layers:

>>> psd.layers
[<psd_tools.Group: 'Group 2', layer_count=1>,
 <psd_tools.Group: 'Group 1', layer_count=1>,
 <psd_tools.Layer: 'Background', size=100x200, x=0, y=0>]

Work with a layer group:

>>> group2 = psd.layers[0]
>>> group2.name
Group 2

>>> group2.visible

>>> group2.closed

>>> group2.opacity

>>> from psd_tools.constants import BlendMode
>>> group2.blend_mode == BlendMode.NORMAL

>>> group2.layers
[<psd_tools.Layer: 'Shape 2', size=43x62, x=40, y=72)>]

Work with a layer:

>>> layer = group2.layers[0]
>>> layer.name
Shape 2

>>> layer.bbox
BBox(x1=40, y1=72, x2=83, y2=134)

>>> layer.bbox.width, layer.bbox.height
(43, 62)

>>> layer.visible, layer.opacity, layer.blend_mode
(True, 255, u'norm')

>>> layer.text_data.text
'Text inside a text box'

>>> layer.as_PIL()
<PIL.Image.Image image mode=RGBA size=43x62 at ...>

Export a single layer:

>>> layer_image = layer.as_PIL()
>>> layer_image.save('layer.png')

Export the merged image:

>>> merged_image = psd.as_PIL()
>>> merged_image.save('my_image.png')

The same using Pymaging:

>>> merged_image = psd.as_pymaging()
>>> merged_image.save_to_path('my_image.png')
>>> layer_image = layer.as_pymaging()
>>> layer_image.save_to_path('layer.png')

Export layer group (experimental):

>>> group_image = group2.as_PIL()
>>> group_image.save('group.png')

Why yet another PSD reader?

There are existing PSD readers for Python:

  • psdparse;
  • pypsd;
  • there is a PSD reader in PIL library;
  • it is possible to write Python plugins for GIMP.

PSD reader in PIL is incomplete and contributing to PIL is complicated because of the slow release process, but the main issue with PIL for me is that PIL doesn't have an API for layer groups.

GIMP is cool, but it is a huge dependency, its PSD parser is not perfect and it is not easy to use GIMP Python plugin from your code.

I also considered contributing to pypsd or psdparse, but they are GPL and I was not totally satisfied with the interface and the code (they are really fine, that's me having specific style requirements).

So I finally decided to roll out yet another implementation that should be MIT-licensed, systematically based on the specification (it turns out the specs are incomplete and sometimes incorrect though); parser should be implemented as a set of functions; the package should have tests and support both Python 2.x and Python 3.x.

Design overview

The process of handling a PSD file is split into 3 stages:

  1. "Reading": the file is read and parsed to low-level data structures that closely match the specification. No user-accessible images are constructed; image resources blocks and additional layer information are extracted but not parsed (they remain just keys with a binary data). The goal is to extract all information from a PSD file.
  2. "Decoding": image resource blocks and additional layer information blocks are parsed to a more detailed data structures (that are still based on a specification). There are a lot of PSD data types and the library currently doesn't handle them all, but it should be easy to add the parsing code for the missing PSD data structures if needed.

After (1) and (2) we have an in-memory data structure that closely resembles PSD file; it should be fairly complete but very low-level and not easy to use. So there is a third stage:

  1. "User-facing API": PSD image is converted to an user-friendly object that supports layer groups, exporting data as PIL.Image or pymaging.Image, etc.

Stage separation also means user-facing API may be opinionated: if somebody doesn't like it then it should possible to build an another API based on lower-level decoded PSD file.

psd-tools tries not to throw away information from the original PSD file; even if the library can't parse some info, this info will be likely available somewhere as raw bytes (open a bug if this is not the case). This should make it possible to modify and write PSD files (currently not implemented; contributions are welcome).



  • reading of RGB and RGBA images;
  • 8bit, 16bit and 32bit channels;
  • all PSD compression methods are supported (not only the most common RAW and RLE);
  • image ICC profile is taken into account;
  • many image resource types and tagged block types are decoded;
  • Descriptor structures are decoded;
  • there is an optional Cython extension to make the parsing fast;
  • very basic & experimental layer merging.

Not implemented:

  • reading of CMYK, Duotone, LAB, etc. images;
  • many image resource types and tagged blocks are not decoded (they are attached to the result as raw bytes);
  • raw Descriptor values (like EngineData) are not decoded;
  • some Descriptor data may be unavailable after loading (even in binary form);
  • this library can't reliably blend layers together: it is possible to export a single layer and to export a final image, but rendering of e.g. layer group may produce incorrect results;
  • the writing of PSD images is not implemented;
  • only 8bit images can be converted to pymaging.Image;
  • layer merging currently doesn't work with Pymaging.

If you need some of unimplemented features then please fire an issue or implement it yourself (pull requests are welcome in this case).


Development happens at github and bitbucket:

The main issue tracker is at github: https://github.com/kmike/psd-tools/issues

Feel free to submit ideas, bugs, pull requests (git or hg) or regular patches.

In case of bugs it would be helpful to provide a small PSD file demonstrating the issue; this file may be added to a test suite.


Unfortunately I don't have a license for Adobe Photoshop and use GIMP for testing; PNG screenshots may be necessary in cases where GIMP fails.

In order to run tests, install tox and type


from the source checkout.

The license is MIT.


A full list of contributors can be found here: https://github.com/kmike/psd-tools/blob/master/AUTHORS.txt

Thanks to all guys who write PSD parsers: I learned a lot about PSD file structure from the source code of psdparse, GIMP, libpsd and psdparse C library; special thanks to Paint.NET PSD Plugin authors for deciphering the "32bit layer + zip-with-prediction compression" case.

0.8.4 (2013-06-12)

  • Point and Millimeter types are added to UnitFloatType (thanks Doug Ellwanger).

0.8.3 (2013-06-01)

  • Some issues with descriptor parsing are fixed (thanks Luke Petre).

0.8.2 (2013-04-12)

  • Python 2.x: reading data from file-like objects is fixed (thanks Pavel Zinovkin).

0.8.1 (2013-03-02)

  • Fixed parsing of layer groups without explicit OPEN_FOLDER mark;
  • Cython extension is rebuilt with Cython 0.18.

0.8 (2013-02-26)

  • Descriptor parsing (thanks Oliver Zheng);
  • text (as string) is extracted from text layers (thanks Oliver Zheng);
  • improved support for optional building of Cython extension.

0.7.1 (2012-12-27)

  • Typo is fixed: LayerRecord.cilpping should be LayerRecord.clipping. Thanks Oliver Zheng.

0.7 (2012-11-08)

  • Highly experimental: basic layer merging is implemented (e.g. it is now possible to export layer group to a PIL image);
  • Layer.visible no longer takes group visibility in account;
  • Layer.visible_global is the old Layer.visible;
  • psd_tools.user_api.combined_bbox made public;
  • Layer.width and Layer.height are removed (use layer.bbox.width and layer.bbox.height instead);
  • pil_support.composite_image_to_PIL is renamed to pil_support.extract_composite_image and pil_support.layer_to_PIL is renamed to pil_support.extract_layer_image in order to have the same API for pil_support and pymaging_support.

0.6 (2012-11-06)

  • psd.composite_image() is renamed to psd.as_PIL();
  • Pymaging support: psd.as_pymaging() and layer.as_pymaging() methods.

0.5 (2012-11-05)

  • Support for zip and zip-with-prediction compression methods is added;
  • support for 16/32bit layers is added;
  • optional Cython extension for faster zip-with-prediction decompression;
  • other speed improvements.

0.2 (2012-11-04)

  • Initial support for 16bit and 32bit PSD files: psd-tools v0.2 can read composite (merged) images for such files and extract information (names, dimensions, hierarchy, etc.) about layers and groups of 16/32bit PSD; extracting image data for distinct layers in 16/32bit PSD files is not suported yet;
  • better Layer.__repr__;
  • bbox property for Group.

0.1.4 (2012-11-01)

Packaging is fixed in this release.

0.1.3 (2012-11-01)

  • Better support for 32bit images (still incomplete);
  • reader is able to handle "global" tagged layer info blocks that was previously discarded.

0.1.2 (2012-10-30)

  • warn about 32bit images;
  • transparency support for composite images.

0.1.1 (2012-10-29)

Initial release (v0.1 had packaging issues).

Subscribe to package updates

Last updated Sep 20th, 2013

Download Stats

Last month:20

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.