PhotoCraft LogoPhotoCraft

PhotoCraft Guides

Practical documentation distilled from the upstream storytold/photocraft project—installers, PSD workflows, agent-ready CLI, and building from source. PhotoCraft is early alpha: expect rough edges, and check the release notes for the version you download.

What PhotoCraft is

PhotoCraft is an open-source, clean-room reimplementation of Adobe Photoshop in pure Rust. It offers layers, masks, adjustment layers, layer styles, type, vectors, brushes, and real PSD/PSB files in a native app—offline, dual-licensed MIT or Apache-2.0, and yours to use and study.
Menus, shortcuts, panels, and tools are intentionally familiar. A GPU compositor on wgpu (Metal, Vulkan, DX12, WebGPU), copy-on-write tiles, and multithreaded filters keep editing local and fast—no Electron shell required for the desktop app.
  • Status: early alpha. Much of Photoshop’s feature surface exists in some form, but it is not yet a daily Photoshop replacement for every professional workflow.
  • Biggest gaps today: AI/generative features, some missing tools, depth in typography and pro workflows, and plug-in compatibility.
  • Honest expectation: every Photoshop menu item may be wired to a command, but wiring is not full behavioural parity. Prefer the upstream roadmap and parity notes for the latest picture.
  • Trademark note: Adobe and Photoshop are trademarks of Adobe Inc. PhotoCraft is independent and not affiliated with Adobe.

Download and install

Official installers and packages for macOS, Windows, Linux, FreeBSD, and the web build are attached to each GitHub release. Start from this site’s Download page, or open the upstream Releases page for every artifact and checksums.

Prefer the Download page on photocraftdl.com for a curated set of links, or browse GitHub Releases for every platform build. Each release ships SHA256SUMS.txt so you can verify what you downloaded.

Platform packages (filename pattern)

PlatformWhat to grab
WindowsMSI installers and portable ZIPs for x64, arm64, and x86 (e.g. photocraft-<ver>-windows-x64.msi). Installers and executables are code-signed.
macOSUniversal DMG for Apple silicon + Intel (photocraft-<ver>-macos-universal.dmg), signed and notarized. Optional CLI: photocraft-cli-<ver>-macos-universal.zip.
LinuxAppImage, Flatpak, .deb, .rpm, and tarball for x86_64 and aarch64. AppImage can self-update via AppImageUpdate (.zsync).
FreeBSDx86_64 tarball laid out like /usr/local (install runtime deps with pkg, then unpack).
Webphotocraft-web-<ver>.zip — a static site that runs in a modern browser; host it on any static server, or try the in-browser editor elsewhere on this site when available.

Linux Flatpak quick start

  • The Flatpak bundle needs the freedesktop runtime from Flathub; flatpak will offer to install it.
  • flatpak install --user photocraft-<version>-linux-x86_64.flatpak (or the aarch64 build)
  • flatpak run ai.storyteller.photocraft

Linux AppImage tip

  • No install required. On first run it can register a launcher icon and menu entry under ~/.local/share so the dock shows PhotoCraft’s icon on Wayland.
  • Set PHOTOCRAFT_NO_DESKTOP_INTEGRATION=1 to skip desktop integration.

macOS CLI notarization

The CLI zip is signed with the same Developer ID as the app and notarized by Apple. A bare binary cannot carry a stapled ticket the way the DMG does, so the first run may check notarization online. You can verify with:

  • ditto -x -k photocraft-cli-<version>-macos-universal.zip .
  • spctl --assess --type install -vv photocraft-cli-<version>-macos-universal/photocraft-cli
  • Expect something like: accepted, source=Notarized Developer ID.

FreeBSD 14 (x86_64)

  • pkg install libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
  • tar -xzf photocraft-<version>-freebsd-x86_64.tar.gz --strip-components 1 -C /usr/local
  • photocraft

First launch and everyday editing

Open a document, learn the familiar tool surface, and know a few Linux/Wayland quirks before you dig into PSD round-trips or automation.

Launch PhotoCraft and open an image or PSD with File › Open, or pass a path when starting from a terminal (for example photocraft image.psd after a source build). Editing stays on your machine—there is no cloud account requirement for core tools.

What you can expect in the box

  • 53 tools spanning marquees, lassos, Object/Quick Selection, brushes, healing, type, pen/shapes, dodge/burn, and more.
  • Layers done properly — groups, clipping masks, pixel and vector masks, fill and adjustment layers, smart objects with smart filters, blend modes, opacity/fill, and history.
  • Adjustment layers that keep edits live (Levels, Curves, Vibrance, Hue/Saturation, and many more) without destroying original pixels.
  • Layer styles such as Drop Shadow, Glows, Bevel & Emboss, Stroke, and overlays—usable on type layers too.
  • Type, vectors, and filters with live filter previews inside selections; Free Transform with full history.
  • Colour depths — RGB, Grayscale, CMYK, and Lab at 8/16/32 bits per channel, with ICC colour management in pure Rust.

Wayland drag-and-drop (Linux)

On a Wayland session, files dropped on the window may not open yet—a limitation in the windowing stack under egui. Workarounds:

  • Use File › Open, or copy an image in your file manager and paste with Ctrl+V.
  • To restore drag-and-drop, start under XWayland: WAYLAND_DISPLAY= photocraft, or the same pattern for AppImage / Flatpak with X11 sockets as documented upstream.

Export and themes

  • Use Export As for format, quality, transparency, and scale with a preview and size estimate; Quick Export can write PNG in one click.
  • Switch between dark Pro, airy Studio, and Classic looks from the app preferences.

PSD, formats, and round trips

PhotoCraft’s PSD support is a standalone crate written from Adobe’s public specification and tested against real-world corpora—not a thin wrapper around proprietary code.

Open, edit, and save layered Photoshop documents. Upstream reports that re-saving keeps the render of 307 of 309 psd-tools test files (and strong results on mixed corpora). A re-saved file is not byte-identical to its source: image resources, layer records, and the composite are rewritten. Unsupported raw blocks and descriptors are carried over instead of dropped when possible.

Formats beyond PSD

  • PSD / PSB — including large documents, 16/32-bit, CMYK, and Lab.
  • Layered TIFF — Photoshop layer data in TIFF, either byte order.
  • OpenRaster — read/write with layers, groups, and blend modes (Krita, MyPaint, GIMP).
  • Paint.NET PDN3 — read with editable layers; SVG can open as shapes or place as a vector Smart Object.
  • Flat formats — PNG, JPEG, TIFF, WebP, GIF, BMP, TGA, ICO, QOI, PNM, OpenEXR, Radiance HDR, plus native .pcraft.
  • Optional / limited: HEIC read-only in official builds; AVIF write with an optional feature; Affinity documents open read-only with warnings for unsupported parts.

Tips for reliable PSD work

  • Keep a copy of important source PSDs before heavy round-trips while you evaluate early-alpha behaviour.
  • If something looks wrong after re-save, note OS, document size, layer count, and a screenshot when filing an issue upstream.
  • For codec details per format, see the upstream codecs capability matrix in the repository docs.

CLI, batch, and agents

Every menu item, tool, and dialog runs through one registry of 500+ commands. The UI, CLI, JSON control channel, and MCP server call the same engine—so anything you can click, a script or agent can drive too.

Headless editing example (command names and params follow upstream CLI help for your installed version):
  • photocraft-cli run wave.psd --cmd filter.sharpen.smartSharpen --params '{"amount":80}' --cmd layer.newAdjustmentLayer.curves --params '{"points":[[0,0],[64,48],[192,212],[255,255]]}' --out wave-final.png
  • photocraft-cli batch --actions grade.json --in ./raw --out ./graded
  • photocraft-cli batch --help — every subcommand explains itself.
  • photocraft-cli mcp — let an agent drive PhotoCraft over MCP (headless, or bridged to a running app).

Desktop control channel

The desktop app can expose an authenticated, loopback-only control channel (photocraft --control) for inspecting UI state, driving tools with pointer events, and taking offscreen screenshots. Upstream documents the protocol in docs/control-protocol.md.

Build from source

Clone the upstream repository, run the desktop app in release mode, and optionally point at craft-fonts for bundled CJK UI/type fonts.

You need a recent Rust toolchain. New contributors and AI agents should start with upstream AGENTS.md, then the docs/ tree and documentation book.

Minimal desktop run

  • git clone https://github.com/storytold/photocraft
  • cd photocraft
  • cargo run --release -p photocraft -- image.psd
  • cargo test --workspace — run the test suite when you change code.

Optional Japanese / CJK fonts (craft-fonts)

Japanese fonts for the UI and Type tool come from craft-fonts, an optional build input (desktop release builds always include it). Without it, PhotoCraft uses your system’s CJK fonts:

  • git clone https://github.com/storytold/craft-fonts ../craft-fonts
  • CRAFT_FONTS_DIR="$PWD/../craft-fonts" cargo run --release -p photocraft

Test corpora

  • PhotoCraft is tested against real files (oracle PSDs, psd-tools, ag-psd, PngSuite), pinned and checksum-verified.
  • Fetch with cargo xtask corpus --all and run with cargo xtask test-corpus (details in upstream docs/development.md).

Stay aligned with upstream

Flags, package names, and parity status change with each release. Prefer the README, Releases notes, and docs for the commit or tag you checked out over older community snapshots. Upstream repository: github.com/storytold/photocraft.

Getting help

When something breaks, file an issue with your OS, document size, layer count, and a screenshot. You can also ask on the ArtCraft Discord linked from the upstream project page.