---
title: Troubleshooting WebGL
order: 5
desc: Diagnose and fix common WebGL issues in Penpot, enable WebGL rendering (Beta), and troubleshoot browser, GPU, and system checks.
---

<h1 id="troubleshooting-webgl">Troubleshooting WebGL</h1>

<div class="advice">
  <h3>WebGL rendering (Beta)</h3>
  <p>Since <strong>Penpot 2.16</strong>, optional <strong>WebGL rendering (Beta)</strong> is available on <code>design.penpot.app</code> and self-hosted instances. It is <strong>off by default</strong>.</p>
  <p>Turn it on from <strong>Your account → Settings</strong> or <strong>Workspace → Main menu → Preferences</strong> when you want a faster canvas for complex files.</p>
  <p>In this beta, WebGL applies to the <strong>design workspace canvas</strong> only. View mode and exports still use the legacy renderer, so some visual differences are expected. If the beta gets in your way, you can switch back to the legacy renderer at any time.</p>
  <p>For what is in scope today, what we are prioritizing next, and known visual differences, read <a href="https://community.penpot.app/t/whats-next-for-the-penpot-webgl-renderer/10627" target="_blank">What's next for the Penpot WebGL renderer</a> on the Penpot Community.</p>
</div>

<p class="main-paragraph">When WebGL rendering (Beta) is enabled, Penpot uses WebGL to render the design workspace canvas. If WebGL is unavailable in your browser, Penpot cannot use that renderer and the workspace canvas may not open correctly.</p>

<p>Sometimes WebGL appears enabled in your browser, but Penpot still cannot create a graphics context. This is usually related to browser settings, GPU acceleration, drivers, or temporary GPU overload.</p>

<h2>Before changing anything</h2>
<ol>
  <li>Open <a href="https://get.webgl.org/" target="_blank">https://get.webgl.org</a>.</li>
  <li>Check the result:
    <ul>
      <li>If you see a spinning cube, WebGL works at browser level.</li>
      <li>If it fails (blank page, error message, or no animation), continue with browser and system checks below.</li>
    </ul>
  </li>
</ol>

<h2>Quick checks (2 minutes)</h2>
<ol>
  <li>Close graphics-heavy tabs/apps (video editors, 3D apps, many design tabs).</li>
  <li>Reload Penpot.</li>
  <li>Fully restart the browser.</li>
  <li>If needed, restart your computer.</li>
</ol>
<p>Why this helps: GPU memory or context slots can be temporarily exhausted, even when your configuration is correct.</p>

<h2>Chrome</h2>
<ol>
  <li>Open <code>chrome://settings/system</code>.</li>
  <li>Turn on <strong>Use graphics acceleration when available</strong>.</li>
  <li>Restart Chrome.</li>
  <li>Open <code>chrome://gpu</code> and review WebGL-related warnings.</li>
</ol>
<figure>
  <a href="/img/troubleshooting/troubleshooting-chrome.webp" target="_blank">
    <img src="/img/troubleshooting/troubleshooting-chrome.webp" alt="Chrome system settings with graphics acceleration option" />
  </a>
</figure>
<p>Why this helps: WebGL depends on hardware acceleration and a healthy GPU process.</p>

<h2>Mozilla Firefox</h2>
<ol>
  <li>Open Firefox and check that zoom is set to <strong>100%</strong> from the top-right menu.</li>
  <li>From that same menu, open Settings/Preferences.</li>
  <li>In General settings, confirm Firefox is up to date and run <strong>Check for updates</strong> if needed.</li>
  <li>Enable hardware acceleration in Firefox settings.</li>
  <li>Restart Firefox.</li>
  <li>Open <code>about:support</code> and review the Graphics/WebGL section.</li>
</ol>
<figure>
  <a href="/img/troubleshooting/troubleshooting-firefox.webp" target="_blank">
    <img src="/img/troubleshooting/troubleshooting-firefox.webp" alt="Firefox settings showing hardware acceleration configuration" />
  </a>
</figure>
<p>Why this helps: outdated browser builds, disabled acceleration, or blocked GPU features can prevent context creation.</p>

<h2>Safari</h2>
<ol>
  <li>Update Safari/macOS to the latest available version.</li>
  <li>Restart Safari.</li>
  <li>Re-test in <a href="https://get.webgl.org/" target="_blank">https://get.webgl.org</a>.</li>
</ol>
<p>Why this helps: Safari WebGL behavior is strongly tied to OS/browser version and graphics stack updates.</p>

<h2>Settings</h2>
<p>Some advanced browser configurations or experimental settings can interfere with WebGL. If you have modified these in the past, consider restoring default browser settings or testing in a fresh profile.</p>

<h2>About zoom and trackpad settings</h2>
<p>In some cases, changing browser zoom or trackpad settings is suggested as a workaround.</p>
<p>In Penpot, these are <strong>not baseline requirements</strong> for WebGL. Treat them only as temporary diagnostics if support explicitly asks for them.</p>
<p>If you temporarily changed one of these settings and Penpot starts working, you can usually revert it and test again.</p>

<h2>GPU drivers and OS checks</h2>
<ol>
  <li>Install any pending OS updates.</li>
  <li>Update GPU drivers (especially on Windows/Linux).</li>
  <li>Disable graphics overlays/tools (recording overlays, GPU tuning utilities) and test again.</li>
</ol>
<p>Why this helps: outdated or conflicting graphics layers can break WebGL context creation.</p>

<h2>Known edge case: Linux + Nvidia</h2>
<p>Some Linux + Nvidia combinations can report WebGL as available but still fail at runtime in specific browser/driver combinations.</p>
<p>In some cases, switching between proprietary and open-source drivers or updating the NVIDIA driver resolves the issue.</p>
<p>If this is your setup, collect diagnostics and contact support.</p>

<h2>If the issue persists</h2>
<p>If WebGL rendering (Beta) is blocking your work, turn it off in <strong>Your account → Settings</strong> or <strong>Workspace → Preferences</strong> and continue on the legacy renderer while you report the issue.</p>
<p>Please share:</p>
<ul>
  <li>Whether WebGL rendering (Beta) is enabled or disabled.</li>
  <li>Browser and version.</li>
  <li>Operating system and version.</li>
  <li>Result from <a href="https://get.webgl.org/" target="_blank">https://get.webgl.org</a>.</li>
  <li>A screenshot of browser graphics diagnostics (<code>chrome://gpu</code> or <code>about:support</code>).</li>
</ul>

<p>Then contact us at <a href="mailto:support@penpot.app">support@penpot.app</a> or open a GitHub issue at <a href="https://github.com/penpot/penpot/issues" target="_blank">https://github.com/penpot/penpot/issues</a>.</p>