photoshop-python-api drives Photoshop over COM from Windows Python

A Python front end for the Photoshop application itself

Photoshop has a scripting story of its own, built on action descriptors and ExtendScript, and it is not pleasant to drive from a modern Python codebase. photoshop-python-api takes a different route: it exposes the running Photoshop application as an ordinary Python object graph, so the same style of code that manipulates a spreadsheet works on an image. The project is described simply as a Python API for Photoshop, and the homepage hosts documentation with an examples gallery whose images were produced by the API itself. The intended users are pipeline engineers and technical artists who want to generate or modify artwork as part of an automated process rather than by hand, and tool authors who need a Photoshop step inside a larger DCC tool. The whole thing runs on the real application, which is the key point for anyone weighing it: nothing here rasterises an image independently of Photoshop, so fidelity to Photoshop's own rendering is inherent rather than approximated.

COM is the transport, and that is why it is Windows only

The mechanism underneath is the Component Object Model. The documentation states that since it uses COM to connect to Photoshop, it can be used in any DCC software with a Python interpreter, which is a useful consequence: the API is not tied to a Python that ships with a particular digital content creation package, it just needs a Python process on Windows that can talk to COM. The dependency list confirms the approach, with comtypes pinned in the project metadata at version 1.4.15 for Python 3.9 and up, and 1.1.11 up to but not including 1.4.13 for older interpreters. The cost of that design is the platform restriction that the project states plainly, only for the Windows platform. There is also a JavaScript escape hatch, since the object model exposes a way to run JavaScript in the application itself, which the examples cover in a file named eval_javascript.py. That path is how you reach Photoshop features the wrapper has not modelled, and it is also how you can break a session badly, since it hands you the raw scripting environment.

Installation is a single pip command on a Windows machine

The install path is short because the package is a pure Python wrapper around a Windows system interface. The documentation gives the install as:

pip install photoshop_python_api

The distribution name on PyPI separates the words with underscores, while the import name uses dots, which trips people up once per project. The project metadata in pyproject.toml is built with Poetry, and the package itself is a single top level package named photoshop. Python support is declared as 3.8 and newer but below 4.0, with classifiers for 3.8 through 3.12, and the Windows 10 and Windows 11 operating system classifiers are listed explicitly. The project is still marked with a Beta development status classifier, which is worth noting for a library that talks to a desktop application through an object model: the surface is wide, and the failure modes usually come from Photoshop's own state rather than from Python.

Creating a document, a layer and coloured text in one script

The hello world example is short enough to read in full, and it shows the shape of every script that uses this API. You open the application, add a document, add an art layer to it, build a SolidColor, set the layer kind to a text layer, write its contents, position it, size it, colour it, then save a copy as a JPEG:

import photoshop.api as ps
app = ps.Application()
doc = app.documents.add()
new_doc = doc.artLayers.add()
text_color = ps.SolidColor()
text_color.rgb.red = 0
text_color.rgb.green = 255
text_color.rgb.blue = 0

The colour object is mutated field by field rather than constructed from a value, and the layer's text properties are set as attributes on a textItem, with position given as a two element list. The save step then exports:

options = ps.JPEGSaveOptions(quality=5)
# # save to jpg
jpg = 'd:/hello_world.jpg'
doc.saveAs(jpg, options, asCopy=True)

The asCopy argument matters in a pipeline, because it leaves the working document open and unsaved by the export path, so a script can save several formats from the same state.

Session wraps a Photoshop instance in a context manager

Managing the lifetime of the application object is the other half of the API, and the documentation offers a context manager for it. You import Session and run your work inside a with block, using action="new_document" to state what the session should open:

from photoshop import Session

with Session(action="new_document") as ps:
    doc = ps.active_document
    text_color = ps.SolidColor()
    text_color.rgb.green = 255
    new_text_layer = doc.artLayers.add()
    new_text_layer.kind = ps.LayerKind.TextLayer
    new_text_layer.textItem.contents = 'Hello, World!'

Inside the block the session exposes the active document directly and the application under ps.app, which is where the JavaScript call lives. The difference from the manual style is real: with Session, you do not hold a ps.Application() reference yourself, and the session decides how the application is reached and released. For long running batch jobs that is the difference between a script that cleans up and one that leaves a Photoshop process behind, and it is why the context manager form is the better default even though the plain application object is the more familiar example.

The examples directory is the real API documentation

The repository layout says more about the project than the README does. The photoshop/ directory holds the package itself, and examples/ contains a long list of one file per operation, among them active_layer.py, add_metadata.py, apply_filters.py, color.py, compare_colors.py, copy_and_paste.py, create_new_document.py, create_thumbnail.py, cropping.py, current_tool.py, delete_and_fill_selection.py, do_photoshop_action.py, emboss_action.py, enable_generator.py, eval_javascript.py, export_artboards.py, export_document.py and export_document_with_options.py. That list is a catalogue of what is actually reachable, and the presence of do_photoshop_action.py and eval_javascript.py confirms that the wrapper is a convenience layer over a much larger application. Documentation is built with mkdocs, with the published site at loonghao.github.io/photoshop-python-api and the readthedocs URL in the project metadata, and the repository also ships llms.txt and llms-full.txt, which are machine readable documentation files aimed at language models. Development tooling is modern: pytest, ruff, mypy, pylint, pre-commit, codecov, coverage, Poetry and release-please for versioning, plus renovate.json for dependency updates.

Version support, release cadence and the Beta label

The supported application versions are stated as a table rather than prose: the project says it has been tested and used with Photoshop 2025, 2024, 2023, 2022, 2021, 2020, cc2019, cc2018 and cc2017, and the badge set in the README covers the same range from cc2017 upward. That is a broad span for a wrapper around a proprietary application, and it implies the object model has stayed broadly stable across those releases, but it also means a version outside that list is untested territory. On the code side, the tags show v0.24.2 on 2026-03-25, v0.24.1 on 2025-05-07 and v0.24.0 on 2024-12-29, while the version field in pyproject.toml reads 0.25.0, so the packaged version and the last tagged release can differ. The last push to the repository was on 2026-10-18, and a bumpversion workflow in the repository handles version bumps. The licence is MIT, which is the permissive option and carries no copyleft requirement for code that merely imports the package.

Editorial conclusion

Adopt photoshop-python-api if you run Photoshop on Windows and need repeatable batch work such as generating artboards, applying filters, exporting images or stamping text into a layout from Python. Do not adopt it for macOS or Linux pipelines, since the transport is COM and the project states it is only for the Windows platform. Verify first that your Photoshop build appears in the supported version table, that the comtypes and wheel pins in pyproject.toml still resolve for your interpreter, and that the pip release you install matches the version you read the docs for, because the project version in pyproject.toml and the latest tagged release can differ.

Frequently asked questions

Official sources

1. License: MIT
2. loonghao/photoshop-python-api on GitHub
3. Project website
4. README
5. Releases