github/penpot
1
0
Fork 0
mirror of https://github.com/penpot/penpot.git synced 2026-07-29 09:26:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

📚 Update troubleshooting WebGL doc (#10233)

Browse Source
This commit is contained in:
andrés gonzález 2026-06-16 16:03:14 +02:00 committed by GitHub
parent 92c9517322
commit 565e173918
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 9 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/user-guide/first-steps/troubleshooting-webgl.njk
View File

@ -1,18 +1,20 @@
---
title: Troubleshooting WebGL
order: 5
desc: Diagnose and fix common WebGL issues in Penpot with browser, GPU, and system checks so you can open the workspace canvas correctly.
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>Availability note</h3>
<p>WebGL renderer is currently not available yet in Penpot production (<code>design.penpot.app</code>).</p>
<p>Right now, this renderer is available only in <strong>testing environments</strong>. It is planned for an upcoming release and should be available soon.</p>
<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">Penpot uses WebGL to render the design canvas. If WebGL is unavailable, Penpot cannot open the workspace canvas correctly.</p>
<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>
@ -96,8 +98,10 @@ desc: Diagnose and fix common WebGL issues in Penpot with browser, GPU, and syst
<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>