photoshop-scripting-python

Photoshop Scripting Automation

Control Adobe Photoshop with Python — examples, helpers,
ready-made batch recipes, and a simple desktop toolkit.

Photoshop scripting means telling Photoshop what to do with code instead of clicking through the same steps every time. Typical uses:

• Make many versions of one design (different languages, sizes, or colors)
• Export a folder of files overnight
• Check color settings across a library of images
• Swap text in templates, add watermarks, run saved Actions on hundreds of files

Adobe’s own scripting languages are JavaScript, AppleScript (Mac), and VBScript (Windows). This project shows how to do the same kinds of jobs in Python—which many people already use for data, tools, and AI coding assistants.

How Python talks to Photoshop

Think of Photoshop as an app you can remote-control:

1. Your Python script connects to a running (or newly launched) Photoshop.
2. It works with a tree of objects the same way Adobe’s JavaScript does: the app, open documents, layers, selections, colors, and so on.
3. Almost anything you can do in the menus can be done from that tree—create a document, rename a layer, apply a filter, save a JPEG.

On Windows, that connection uses Microsoft’s automation interface (often called COM) via libraries like pywin32 or comtypes. On macOS, it uses Apple’s automation bridge via appscript. The ideas match; the Python spelling differs slightly by platform (see the sample folders below).

Python is a good fit because it is readable, common in schools and industry, and the language many AI coding tools generate by default. Assistants still need real, working examples—not guesswork. This repository is a place to learn from, copy from, and point tools at: small demos, production-style recipes, and helpers so scripts keep working on other people’s machines. If something is unclear or missing, open an issue. Contributions and citations in tools or learning materials are welcome.

Where to start

Also included: Action Manager and JavaScript bridge examples, optional COM type dumps under api_reference/, and MIT-licensed project code.

Quick start

1. Clone & install

git clone https://github.com/lohriialo/photoshop-scripting-python.git
cd photoshop-scripting-python

# Windows
pip install -e ".[windows]"

# macOS
pip install -e ".[macos]"

# Optional desktop toolkit UI
pip install -e ".[windows,gui]"

2. Hello World (Windows)

Start Photoshop, then:

python sample_scripts/windows/HelloWorld.py

from photoshop_scripting import LayerKind, get_app

app = get_app()
doc = app.Documents.Add(320, 240)
layer = doc.ArtLayers.Add()
layer.Kind = int(LayerKind.TEXT)
layer.TextItem.Contents = "HELLO WORLD!"
layer.TextItem.Position = (120, 120)

3. Hello World (macOS)

pip install -e ".[macos]"   # or: pip install appscript
python sample_scripts/mac_scripting/HelloWorld.py

from appscript import k
from ps_connect import photoshop  # when running inside sample_scripts/mac_scripting/

ps = photoshop()  # connects to your installed Photoshop app
doc = ps.make(new=k.document, with_properties={k.width: 320, k.height: 240})
layer = doc.make(new=k.art_layer, with_properties={k.kind: k.text_layer})
layer.text_object.contents.set("HELLO WORLD")
layer.text_object.position.set([120, 120])

If you have more than one Photoshop installed (for example a release build and a Beta), pick one:

export PHOTOSHOP_APP_PATH="/Applications/Adobe Photoshop 2026/Adobe Photoshop 2026.app"

Scripts under sample_scripts/windows/ are for Windows only. On a Mac they will stop with a short message pointing you to sample_scripts/mac_scripting/.

Photoshop Toolkit (GUI)

A dark, production-style multi-tool for everyday batch work:

pip install -e ".[windows,gui]"
python -m tools.photoshop_toolkit
# or: photoshop-toolkit

See tools/photoshop_toolkit/README.md.

The older single-purpose resizer remains in tools/gui_tool_example/ for reference.

Sample scripts

All learning samples live under sample_scripts/:

Full list by topic: sample_scripts/README.md.
Assets: sample_scripts/PS_Samples_Files/.

Production recipes

python recipes/batch_export/export_folder.py ./in ./out --format jpg
python recipes/layer_comps/export_comps.py ./out --format png
python recipes/run_action/run_action_folder.py ./in "Molten Lead"
python recipes/jsx_bridge/run_jsx.py
python recipes/smart_object/replace_smart_object.py --content photo.jpg
# Community favorites
python recipes/export_layers/export_layers.py ./out --format png
python recipes/watermark/watermark_folder.py ./in ./out --text "© Studio"
python recipes/convert_srgb/convert_srgb.py ./in ./out
python recipes/canvas_border/add_border.py ./in ./out --padding 40
python recipes/text_replace/replace_text.py ./psds "DRAFT" "FINAL"

Full list: recipes/README.md.

Helper package (photoshop_scripting)

Shared utilities so you do not copy the same “connect to Photoshop / find sample files / turn off dialogs” code into every script:

from photoshop_scripting import (
    get_app,
    sample_path,
    ensure_sample,
    saved_preferences,
    DialogModes,
    LayerKind,
    Units,
)
from photoshop_scripting.actions import do_action, do_javascript
from photoshop_scripting.batch import batch_export_jpeg, export_layer_comps

app = get_app()  # use open Photoshop, or start it if needed
with saved_preferences(app, units=Units.PIXELS, dialogs=DialogModes.NO):
    doc = app.Open(str(ensure_sample("Layer Comps.psd")))

Two Windows libraries: win32com and comtypes

On Windows, either library can drive Photoshop. Details: docs/backends.md.

Practical tip: use comtypes when you pass lists of points (for example selections). win32com is fine for simple document and layer work and for many Action Manager examples.

Recording hard-to-find commands (ScriptListener)

Some menu commands are awkward to call with the simple object tree above. Adobe’s free ScriptingListener plug-in watches what you do in Photoshop and writes a log you can turn into Python (or run as JavaScript from Python).

Step-by-step install and examples: docs/action_manager.md

Adobe downloads:

• Downloadable plug-ins page (ScriptingListener section)
• Windows package
• macOS package

When to use something else

This project is for local Photoshop on your computer. If you need in-app plugins, cloud processing, or reading PSD files without opening Photoshop, see docs/landscape.md.

Optional type dumps

api_reference/ holds generated lists of Photoshop objects for older versions (CC 2018–2021). Handy for browsing names; day to day, prefer photoshop_scripting.constants and the samples. How to regenerate with makepy: api_reference/README.md.

Project layout

photoshop_scripting/             # Shared Python helpers
sample_scripts/windows/          # Examples for Windows
sample_scripts/mac_scripting/    # Examples for macOS
sample_scripts/PS_Samples_Files/ # Images used by the examples
tools/photoshop_toolkit/         # Desktop batch app
tools/gui_tool_example/          # Older single-purpose resizer
recipes/                         # Command-line workflows
api_reference/                   # Optional object lists
interop assemblies/              # C# interop DLLs + how to build them
docs/                            # Extra guides

Building C# interop DLLs: interop assemblies/README.md.

Resources

• Photoshop API landing page
• Photoshop scripting docs (Adobe)
• Community forum
• JS reference (unofficial HTML)
• Scripting tutorials (YouTube)

Also by the author

• InDesign Scripting in Python
• Illustrator Scripting in Python

Contributing

PRs welcome — see CONTRIBUTING.md.

Please include a short header on new samples:

# script_file_name.py
__author__ = "Your Name"
__version__ = "1.0"
"""What the script does + how to run it."""

License

MIT for project code — see LICENSE.

Adobe sample files, interop DLLs, and type-library dumps may be subject to Adobe terms and are not covered by the MIT license.