Diagnosing Firefox GPU Acceleration Issues with widget.hardware-acceleration.allow-gpu

When to suspect GPU compositing problems

Firefox renders its UI and web content through a compositor that can offload work to the GPU. When this path misbehaves, you see flickering tabs, missing window chrome, corrupted video playback, or crashes on startup — especially after a driver update or on hybrid-graphics laptops. The widget.hardware-acceleration.allow-gpu preference is the primary switch that controls whether Firefox attempts GPU-accelerated widget composition at all.

Quick reference: preference values and effects

Value	Label	Behavior	Typical use case
0	Disabled	Forces CPU rendering for widget composition; WebGL and WebGPU may still use GPU via separate paths	Workaround for driver bugs, black screens, or crashes on specific GPUs
1	Auto (default)	Firefox decides based on blocklist, driver version, and platform heuristics	Normal operation; let the blocklist handle known-bad combinations
2	Forced enabled	Bypasses blocklist and forces GPU compositing even on unsupported configurations	Testing, CI pipelines, or hardware known to work but incorrectly blocklisted

Diagnostic checklist — run in order

1. Confirm the symptom is compositor-related. Open about:support and scroll to Graphics → Compositing. If it reads Basic or Software, GPU compositing is already off. If it shows WebRender or OpenGL but you see artifacts, continue.
2. Check current preference value. In a new tab, enter about:config, accept the warning, and search widget.hardware-acceleration.allow-gpu. Note the integer shown.
3. Test with GPU compositing disabled. Set the preference to 0, restart Firefox (close all windows), and reproduce the issue. If artifacts disappear, the GPU path is the culprit.
4. Test with forced GPU compositing. If step 3 did not help, set the preference to 2, restart, and retest. This confirms whether the blocklist is over-aggressive for your hardware.
5. Cross-check with the legacy switch. Toggle layers.acceleration.disabled to true (requires restart). This disables the entire layers acceleration stack, not just widget composition. If both switches produce identical results, the problem sits deeper in the graphics stack.

Interpreting results and applying fixes

Case A: Artifacts vanish at value 0

Your GPU driver has a compositing bug. Keep widget.hardware-acceleration.allow-gpu = 0 as a stable workaround. Expect higher CPU usage on animated pages and no WebRender benefits. Monitor driver updates; when a new driver ships, retest with value 1.

Case B: Value 0 makes no difference, value 2 stabilizes rendering

Your hardware is capable but blocklisted. File a bug at Bugzilla with about:support output and the driver version. Until the blocklist updates, you can leave the preference at 2, but note this is unsupported and may break after Firefox updates.

Case C: Neither value changes the symptom

The issue is not widget compositing. Common alternatives:

• WebGL/WebGPU crashes: Toggle webgl.disabled or dom.webgpu.enabled instead.
• Video decoding: Check media.hardware-video-decoding.enabled and media.wmf.vp9.enabled.
• Theme/extension interference: Start Firefox in Troubleshoot Mode (Help → Troubleshoot Mode) to isolate add-ons.

Version and channel caveats

• ESR (Extended Support Release): Retains value 0 as a supported compatibility mode longer than Rapid Release. Value 2 may be ignored or cause startup failure on ESR branches older than 115.
• Nightly/Beta: Default heuristics change frequently. A setting that works today may be overridden by a new blocklist entry tomorrow.
• Linux Wayland vs X11: On Wayland, widget composition often uses dmabuf paths that bypass this preference partially. Test both GDK_BACKEND=wayland and GDK_BACKEND=x11 launches if you switch sessions.

Verification after changes

1. Restart Firefox completely (not just a new window).
2. Open about:support again and confirm Compositing shows the expected backend (Basic for value 0, WebRender for value 2 on supported hardware).
3. Load a stress page: https://webglsamples.org/aquarium/aquarium.html or a CSS-transform-heavy site. Watch for frame drops, flicker, or console errors in Ctrl+Shift+J.
4. Check power draw on laptops (powertop or vendor tools) — forced GPU compositing can prevent package C-states.

Escalation criteria

Stop adjusting this preference and seek deeper help when:

• Firefox crashes on startup with MOZ_CRASHREPORTER entries citing gfxCriticalError or GPUProcess.
• Multiple preference combinations (0, 1, 2 plus layers.acceleration.disabled) produce identical failures.
• The issue appears only on a specific site — file a webcompat issue instead.
• You are on a managed enterprise build where policies.json locks HardwareAcceleration; local about:config changes will be reverted on restart.

Rollback procedure

If a change worsens stability, revert in about:config (right-click → Reset) or delete the line from prefs.js in the profile folder while Firefox is closed. No profile reset is required.