Installation

Note

Since the API changes with each release,you may want to check the CHANGELOG.md when you upgrade to a newer version of wgpu.

Install with pip

You can install wgpu-py via pip. Python 3.8 or higher is required. Pypy is supported. Only depends on cffi (installed automatically by pip).

pip install wgpu

Since most users will want to render something to screen, we recommend installing GLFW as well:

pip install wgpu glfw

GUI libraries

Multiple GUI backends are supported, see the GUI API for details:

  • glfw: a lightweight GUI for the desktop

  • jupyter_rfb: only needed if you plan on using wgpu in Jupyter

  • qt (PySide6, PyQt6, PySide2, PyQt5)

  • wx

The wgpu-native library

The wheels that pip installs include the prebuilt binaries of wgpu-native, so on most systems everything Just Works.

On Linux you need at least pip >= 20.3, and a recent Linux distribution, otherwise the binaries will not be available. See below for details.

If you need/want, you can also build wgpu-native yourself. You will then need to set the environment variable WGPU_LIB_PATH to let wgpu-py know where the DLL is located.

Platform requirements

Under the hood, wgpu runs on Vulkan, Metal, or DX12. The wgpu-backend is selected automatically, but can be overridden by setting the WGPU_BACKEND_TYPE environment variable to “Vulkan”, “Metal”, “D3D12”, or “OpenGL”.

Windows

On Windows 10+, things should just work. If your machine has a dedicated GPU, you may want to update to the latest (Nvidia or AMD) drivers.

MacOS

On MacOS you need at least 10.13 (High Sierra) to have Metal/Vulkan support.

Linux

On Linux, it’s advisable to install the proprietary drivers of your GPU (if you have a dedicated GPU). You may need to apt install mesa-vulkan-drivers. On Wayland, wgpu-py requires XWayland (available by default on most distributions).

Binary wheels for Linux are only available for manylinux_2_24. This means that the installation requires pip >= 20.3, and you need a recent Linux distribution, listed here.

If you wish to work with an older distribution, you will have to build wgpu-native yourself, see “dependencies” above. Note that wgpu-native still needs Vulkan support and may not compile / work on older distributions.

Cloud Compute

GPU Environments

WGPU can work in GPU cloud compute environments on Linux machines with no physical display output. By default, these environments may lack system libraries that are typically found on a standard linux desktop. On Debian & Ubuntu based systems you should be able to get everything you need by installing the following in addition to your vendor-specific (Nvidia/AMD) GPU drivers:

sudo apt install xserver-xorg-core mesa-vulkan-drivers libvulkan1

Note

If your distro is not Debian/Ubuntu install the corresponding packages for your distribution.

You can verify whether the “DiscreteGPU” adapters are found:

import wgpu
import pprint

for a in wgpu.gpu.enumerate_adapters():
    pprint.pprint(a.request_adapter_info())

If you are using a remote frame buffer via jupyter-rfb we also recommend installing the following for optimal performance:

sudo apt install libjpeg-turbo8-dev libturbojpeg0-dev
pip install simplejpeg

Your mileage may vary across different cloud service providers, for more info see: https://github.com/pygfx/wgpu-py/issues/493

Installing LavaPipe on Linux

To run wgpu on systems that do not have a GPU (e.g. CI) you need a software renderer. On Windows this (probably) just works via DX12. On Linux you can use LavaPipe:

sudo apt update -y -qq
sudo apt install --no-install-recommends -y libegl1-mesa libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers

The distribution’s version of Lavapipe may be a bit outdated. To get a more recent version, you can use this PPA:

sudo add-apt-repository ppa:oibaf/graphics-drivers -y

Note

The precise visual output may differ between differen implementations of Vulkan/Metal/DX12. Therefore you should probably avoid per-pixel comparisons when multiple different systems are involved. In wgpu-py and pygfx we have solved this by generating all reference images on CI (with Lavapipe).