Start · Install 10 min
When PhotoCraft will not open
Most failed launches are the wrong file, not a broken editor. Check the filename against the machine before you reinstall it a second time.
Confirm you ran the app
The Source code zip and photocraft-web-<ver>.zip do not start a desktop window by themselves. The web zip is a site to host, covered in PhotoCraft in the browser. The desktop names are the MSI, the portable zip, the DMG, the AppImage, the Flatpak, the deb, the rpm, and the platform tarballs in Which PhotoCraft file to download.
An ARM Windows PC needs the arm64 build. An Intel or AMD PC needs x64. The v0.23.1 asset list on the product page had no 32-bit Windows installer. A Mac uses the universal DMG for both Apple silicon and Intel.
Graphics and Wayland
The README describes a GPU compositor on Metal, Vulkan, DirectX 12, and WebGPU. A current driver for that path matters more than another copy of the same installer. On a Mac the canvas uses Metal. On Windows it wants DirectX 12 or Vulkan. On Linux it wants Vulkan.
On a Wayland session the README says files dropped on the window do not open yet. Use File, then Open, or copy the image and paste it. Drag and drop works under XWayland, and the README shows clearing WAYLAND_DISPLAY for that. A fractional scale under XWayland can look soft. Native Wayland stays sharp and keeps the drop limitation.
If a real build still fails
PhotoCraft is early alpha. A crash with the right installer is a bug, not a puzzle you should solve by downloading a third-party mirror. The README asks for the operating system, the document size, the layer count, and a screenshot when you report it.
Report it on the repository or Discord. If the window opens and then closes, the status bar says CPU rendering, or a file is refused for memory, the steps are When the window closes or the canvas is slow. Read What early alpha means before you decide the alpha is ready for work you cannot redo.
Confirm the install itself before you call it a crash
A window that never appears is often the wrong artifact. The source-code zip does not start the editor. The web zip has to be hosted, which is PhotoCraft in the browser. The desktop path is the one in Which PhotoCraft file to download. On Windows, a per-user install needs no administrator, and Everyone on this computer does. Only one installed copy is allowed, so a half-finished switch between those two leaves you with whichever copy you did not remove. The portable build is the exe inside the zip, with PhotoCraftData beside it. On a Mac the app is the one you dragged to Applications from the universal image. On Linux, an AppImage must be the file you launch. A deb you downloaded and never installed is still a file. The Flatpak you start is flatpak run ai.storyteller.photocraft, after flatpak install --user. On FreeBSD the tarball belongs under /usr/local with the libraries the install guide lists.
The install guide still prints 32-bit Windows filenames. The v0.23.1 product-page assets did not include them. An old blog that offers an x86 MSI is not a newer source than the release you have open. Gentoo’s community overlay is optional packaging and is not maintained by the PhotoCraft team. The page these install shapes come from is Install and update.
Flags for a start that needs help
Most people never need a startup flag. You can pass one or more filenames on the command line and PhotoCraft opens them. On Windows and Linux, a file you open while PhotoCraft is already running becomes a new tab in that copy. Add --new-instance when you want a separate copy instead. Some people still see new windows rather than tabs. That report is open, and it is listed with the other open problems on When the window closes or the canvas is slow.
--safe-gpu starts that one launch on the CPU renderer. --in-window-menus keeps the menus inside the window on a Mac instead of the system menu bar. --present-mode takes fifo, autovsync, or novsync, and --frame-latency takes 1, 2, or 3. Those two change how frames reach the display. PHOTOCRAFT_CONFIG_DIR points PhotoCraft’s settings at a folder you choose, which is useful when a portable-style settings directory should not sit in the default place. photocraft --help prints the set. The graphics fallback that happens without flags, Vulkan then DirectX 12 then CPU on Windows, is the longer story on When the window closes or the canvas is slow.
Uninstalling does not delete your images. Windows removes the app from Settings, then Apps. The portable zip is removed by deleting its folder. macOS moves PhotoCraft from Applications to the Trash. Linux uses the package manager, flatpak uninstall ai.storyteller.photocraft, or deletes the AppImage or the unpacked tarball. Settings stay behind until you delete the settings folder. If a real build still closes after the right install, report it with the operating system, the document size, the layer count, and a screenshot. Whether the alpha is the right tool once it does open is What early alpha means.