Python API for Photoshop.

⚠️ Only for Windows platform !

The example above was created with Photoshop Python API. Check it out at https://loonghao.github.io/photoshop-python-api/examples.

Has been tested and used Photoshop version:

Photoshop Version	Supported
2025	✅
2024	✅
2023	✅
2022	✅
2021	✅
2020	✅
cc2019	✅
cc2018	✅
cc2017	✅

Installing

You can install via pip.

pip install photoshop_python_api

Since it uses COM (Component Object Model) connect Photoshop, it can be used in any DCC software with a python interpreter.

Hello World

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
new_text_layer = new_doc
new_text_layer.kind = ps.LayerKind.TextLayer
new_text_layer.textItem.contents = 'Hello, World!'
new_text_layer.textItem.position = [160, 167]
new_text_layer.textItem.size = 40
new_text_layer.textItem.color = text_color
options = ps.JPEGSaveOptions(quality=5)
# # save to jpg
jpg = 'd:/hello_world.jpg'
doc.saveAs(jpg, options, asCopy=True)
app.doJavaScript(f'alert("save to jpg: {jpg}")')

Photoshop Session

Use it as context.

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!'
    new_text_layer.textItem.position = [160, 167]
    new_text_layer.textItem.size = 40
    new_text_layer.textItem.color = text_color
    options = ps.JPEGSaveOptions(quality=5)
    jpg = 'd:/hello_world.jpg'
    doc.saveAs(jpg, options, asCopy=True)
    ps.app.doJavaScript(f'alert("save to jpg: {jpg}")')

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Hal 💻	voodraizer 🐛	brunosly 🐛	tubi 🐛	wjxiehaixin 🐛	罗马钟 🐛	clement 🐛
krevlinmen 🐛	Thomas 🐛	CaptainCsaba 🐛	Il Harper 💻	blunderedbishop 🐛	MrTeferi 💻	Damien Chambe 💻
Ehsan Akbari Tabar 🐛	Michael Ikemann 🐛	Enguerrand DE SMET 💻	Proton 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!

Repobeats analytics

how to get Photoshop program ID

Get-ChildItem "HKLM:\SOFTWARE\Classes" |
  ?{ ($_.PSChildName -match "^[a-z]+\.[a-z]+(\.\d+)?$") -and ($_.GetSubKeyNames() -contains "CLSID") } |
  ?{ $_.PSChildName -match "Photoshop.Application" } | ft PSChildName

How to get a list of COM objects from the registry

Useful links

• https://theiviaxx.github.io/photoshop-docs/Photoshop/
• http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/photoshop/pdfs/photoshop-cc-javascript-ref-2015.pdf
• https://github.com/lohriialo/photoshop-scripting-python
• https://www.adobe.com/devnet/photoshop/scripting.html
• https://www.youtube.com/playlist?list=PLUEniN8BpU8-Qmjyv3zyWaNvDYwJOJZ4m
• http://yearbook.github.io/esdocs/#/Photoshop/Application
• http://www.shining-lucy.com/wiki/page.php?id=appwiki:photoshop:ps_script
• http://www.tonton-pixel.com/wp-content/uploads/DecisionTable.pdf
• http://jongware.mit.edu/pscs5js_html/psjscs5/pc_Application.html
• https://indd.adobe.com/view/a0207571-ff5b-4bbf-a540-07079bd21d75
• http://shining-lucy.com/wiki/page.php?id=appwiki:photoshop:ps_script
• http://web.archive.org/web/20140121053819/http://www.pcpix.com/Photoshop/char.html
• http://www.tonton-pixel.com/scripts/utility-scripts/get-equivalent-id-code/index.html
• https://github.com/Adobe-CEP/CEP-Resources/tree/master/Documentation/Product%20specific%20Documentation/Photoshop%20Scripting
• https://github.com/Adobe-CEP/Samples/tree/master/PhotoshopEvents
• https://evanmccall.wordpress.com/2015/03/09/how-to-develop-photoshop-tools-in-python

🛠️ Development Guide

Welcome to the development guide for the Photoshop Python API project! This section outlines our development practices and standards to ensure code quality and consistency.

📋 Quick Start for Contributors

# Clone the repository
git clone https://github.com/loonghao/photoshop-python-api.git
cd photoshop-python-api

# Install dependencies with Poetry
poetry install

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

🎨 Code Style & Quality

We maintain high code quality standards through automated tools and consistent style guidelines:

• Style Guide: We follow the Google Python Style Guide with project-specific adjustments:

  • Line length: 120 characters max
  • Docstrings: Google style format
  • Quotes: Double quotes preferred

• Quality Tools:

  • Ruff - Linting, formatting, and import organization
  • pre-commit - Automated checks before commits

🔄 Git Workflow

We use a structured workflow to maintain a clean and organized repository:

• Commit Messages: Follow Conventional Commits format

  <type>(<scope>): <description>
  
  [optional body]
  
  [optional footer(s)]
  

  Common types: feat, fix, docs, style, refactor, test, chore

• Branching Strategy:

  • Main branch: main - Always stable and deployable
  • Feature branches: feature/<feature-name>
  • Bug fixes: fix/<bug-description>
  • Documentation: docs/<doc-description>

🧪 Testing

We value thorough testing to ensure reliability:

• Framework: We use pytest for all tests
• Coverage: Aim for high test coverage on new features
• Run Tests: pytest or poetry run pytest

📦 Development Environment

• Python Versions: We support Python 3.10+ (see pyproject.toml for specifics)
• Dependency Management: Poetry for consistent environments
• Virtual Environment: Poetry automatically creates and manages virtual environments

🤝 Contributing Process

1. Fork & Clone: Fork the repository and clone your fork
2. Branch: Create a feature branch with a descriptive name
3. Develop: Make your changes following our code style guidelines
4. Test: Ensure all tests pass and add new tests for new features
5. Commit: Use conventional commit format for clear history
6. Push & PR: Push your branch and create a Pull Request
7. Review: Address any feedback from code reviews
8. Merge: Once approved, your PR will be merged

Thank you for contributing to the Photoshop Python API project! 🎉

Development Notes

One way to view the COM API structure is to use Visual Studio.

1. Install Visual Studio with the .NET desktop development workload
2. Open Visual Studio
3. Choose View -> Object Browser
4. In the Object Browser from the Browse dropdown choose Edit Custom Component Set...
5. In the Edit Custom Component Set window's COM tab add Photoshop's Object and Type libraries
6. After pressing OK the libraries should show up in the Object Browser

If the libraries aren't visible in the COM tab make sure you have the .NET desktop development workload installed. Other things you may try are running Photoshop once as administrator and reinstalling Photoshop and/or your PC. The object library is defined usually in /your/path/to/Adobe Photoshop <version>/Required/Plug-ins/Extensions/ScriptingSupport.8li

The VBS reference 2020 is also quite trustworthy, since Adobe isn't actively developing the COM API anymore.