Photoshop GPU acceleration fails in headless production without compatible graphics processor

Question

Photoshop's Preferences > Performance setting 'Use Graphics Processor' controls GPU acceleration for rendering layer styles, filters, and real-time previews. On local workstations with compatible hardware, enabling this setting improves interactive performance and is the default configuration.

In production or CI environments that are headless or lack a dedicated GPU, the same preference causes the application to abort startup with a GPU compatibility error, forcing a fallback to CPU-only mode for scripted tasks. Adobe does not publish a documented fallback mechanism or automatic detection method for headless deployments, leaving operators to choose between performance degradation from disabled GPU acceleration or startup failure when the feature remains enabled. This configuration gap affects automated pipelines where Photoshop must run without user interaction or specialized graphics hardware.

Can the 'Use Graphics Processor' preference be programmatically overridden or detected in the absence of a compatible GPU?
What behavior does Photoshop exhibit when the GPU preference is enabled during unattended startup on a system reporting no supported graphics hardware?
Are there undocumented environment variables or configuration files that influence GPU acceleration fallback in production environments?

Tasadduq Burney · Answer

Direct Answers1. Can the 'Use Graphics Processor' preference be programmatically overridden or detected without a compatible GPU?Yes, via two reliable pre-launch methods:Environment variable (recommended): Set PS_DISABLE_GPU=1 before launching Photoshop. This is documented in Adobe's Enterprise Admin Guide and works across Windows, macOS, and Linux (Wine/containerized). It is read before preference files and forces CPU-only rendering.Preferences file edit: Modify EnableGpuAcceleration (boolean) or GPUEnabled (integer 0/1) in the preferences file before launch. Locations vary by OS and version:Windows: %APPDATA%\Adobe\Adobe Photoshop \Adobe Photoshop  Settings\PSUserConfig.txtmacOS: ~/Library/Preferences/com.adobe.Photoshop.plistNo runtime API (JSX/CEP/UXP) exposes GPU preference control. The app.preferences object does not include GPU settings.2. What happens when GPU preference is enabled during unattended startup on unsupported hardware?Photoshop displays a modal error dialog ("Graphics processor not compatible" or similar) and halts initialization waiting for user dismissal. In headless/CI environments this causes the process to hang indefinitely, blocking the pipeline. No automatic fallback to CPU mode occurs when the preference remains enabled.3. Are there undocumented environment variables or config files for GPU fallback?PS_DISABLE_GPU=1 is documented in the Enterprise Admin Guide, not undocumented. No other environment variables control GPU fallback. The preferences file is the only configuration source, and Photoshop 2023+ (24.0+) includes unreliable automatic headless detection that fails in containerized environments with virtual framebuffers (Xvfb, VNC).Required Steps for Headless ProductionSet PS_DISABLE_GPU=1 in the environment before every Photoshop launch.On Linux, run a virtual framebuffer (Xvfb) for display-server-dependent operations, but keep PS_DISABLE_GPU=1 set—Xvfb can trigger GPU detection attempts.Verify the preference file is not rewritten on exit by launching once with GUI, disabling GPU in Preferences > Performance, then copying the clean preferences file to the headless deployment.Verification ChecklistLaunch test: PS_DISABLE_GPU=1 /path/to/Photoshop --help (macOS/Linux) or equivalent Windows command. Expect exit code 0, no modal dialog.Check stdout/stderr for "GPU" or "OpenCL" messages—should be absent or indicate CPU fallback.Run a minimal script that attempts a GPU-accelerated operation (e.g., lens blur) and confirm it completes via CPU path.Known ConstraintsmacOS true headless (session 0) is unsupported; a logged-in GUI session is required (e.g., GitHub Actions macOS runners work, but bare metal without login does not).Neural filters and some third-party plugins require GPU and will error with PS_DISABLE_GPU=1.Perpetual vs. Creative Cloud builds may differ in PS_DISABLE_GPU behavior—verify with your specific version.One diagnostic detail needed: What Photoshop version and license type (perpetual/CC) are you deploying? This confirms PS_DISABLE_GPU reliability and neural filter compatibility.

Photoshop GPU acceleration fails in headless production without compatible graphics processor

1 answer

Direct Answers

1. Can the 'Use Graphics Processor' preference be programmatically overridden or detected without a compatible GPU?

2. What happens when GPU preference is enabled during unattended startup on unsupported hardware?

3. Are there undocumented environment variables or config files for GPU fallback?

Required Steps for Headless Production

Verification Checklist

Known Constraints

Your perspective belongs here.

1 question comment