This document explains why WebGPU may be inoperable or not working as expected in Chrome browser, with clear steps to solve the issues where possible.
navigator.gpu is undefined
The following example shows a JavaScript error you may get when gpu
is not available in navigator
:
const adapter = await navigator.gpu.requestAdapter();
cancel Uncaught TypeError: Cannot read properties of undefined (reading 'requestAdapter')
This may be due to one of the following reasons. Check out those in this specific order:
WebGPU requires Chrome 113 or greater on ChromeOS, macOS, Windows and Chrome 121 or greater on Android. Check your version at
chrome://version
and update if necessary.WebGPU is accessible only to secure contexts. If you serve your code over an insecure protocol (for example,
http:
,file:
), either use the securehttps:
protocol or address this during the development of your web app in one of the following ways:Serve your code locally on
http://localhost
orhttp://127.0.0.1
with either of these commands:npx http-server
orpython3 -m http.server
.Add the origin to the "Insecure origins treated as secure" list of
chrome://flags/#unsafely-treat-insecure-origin-as-secure
and restart Chrome.Install Node.js and run
npx servez --ssl
to serve your folder over https with a fake certificate. You'll still get a warning in Chrome you can bypass by clicking "Advanced" then "Proceed to...".Expose your local web server to the Internet with ngrok.
The GPU adapter is null
The following is an example of a JavaScript error you may get when the adapter you get from calling requestAdapter()
is null:
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
cancel Uncaught TypeError: Cannot read properties of undefined (reading requestDevice)
This happens for one of the following reasons. Check out those in this specific order:
WebGPU is disabled when the user has turned off "Use graphics acceleration when available" in
chrome://settings/system
. Check to see if this setting is turned off and turn it back onWebGPU is not supported on this platform yet. You can enable the
chrome://flags/#enable-unsafe-webgpu
flag and restart Chrome. For Linux experimental support, you'll also need to enable thechrome://flags/#enable-vulkan
flag. Check out WebGPU support in Headless Chrome to learn more.The GPU hardware has been specifically blocklisted. If you see "WebGPU has been disabled via blocklist or the command line" in
chrome://gpu
, you can disable the WebGPU adapters blocklist by enabling thechrome://flags/#enable-unsafe-webgpu
flag and restarting Chrome.There is no matching GPU adapter for the options passed in
requestAdapter()
. Try callingrequestAdapter()
with different options.WebGPU requires a GPU (either hardware or software-emulated). You can check if Chrome detects a GPU by visiting
chrome://gpu
.The GPU process crashed several times. You can reload the page or restart Chrome. Check out WebGPU Device Loss best practices to learn more.
WebGPU is slower than WebGL
Open
chrome://gpu
and make sure you can read "WebGPU: Hardware accelerated". If you read "WebGPU: Software only, hardware acceleration unavailable", you may need to update your GPU drivers.Directly translating WebGL concepts to WebGPU might not be taking full advantage of WebGPU's unique optimizations. Check out From WebGL to WebGPU to learn about some of their differences.
Windows-specific limitations
Be aware of the following limitations when using WebGPU on Windows devices:
Chrome does not support using multiple GPU adapters simultaneously. See issue chromium:329211593.
Chrome always uses the same GPU adapter that's been allocated for other Chrome workloads, which for laptops is generally the integrated graphics card, due to the power usage aspect (ie: power saving). It means the
powerPreference
option doesn't have any impact when callingrequestAdapter()
.