Skip to main content

WebGPU for Python

Project description

CI Documentation Status PyPI version

wgpu-py

A Python implementation of WebGPU - the next generation GPU API. 🚀

Introduction

The purpose of wgpu-py is to provide Python with a powerful and reliable GPU API.

It serves as a basis to build a broad range of applications and libraries related to visualization and GPU compute. We use it in pygfx to create a modern Pythonic render engine.

To get an idea of what this API looks like have a look at triangle.py and the other examples.

Status

  • Until WebGPU settles as a standard, its specification may change, and with that our API will probably too. Check the changelog when you upgrade!
  • Coverage of the WebGPU spec is complete enough to build e.g. pygfx.
  • Test coverage of the API is close to 100%.
  • Support for Windows, Linux (x86 and aarch64), and MacOS (Intel and M1).

What is WebGPU / wgpu?

WGPU is the future for GPU graphics; the successor to OpenGL.

WebGPU is a JavaScript API with a well-defined spec, the successor to WebGL. The somewhat broader term "wgpu" is used to refer to "desktop" implementations of WebGPU in various languages.

OpenGL is old and showing its cracks. New API's like Vulkan, Metal and DX12 provide a modern way to control the GPU, but these are too low-level for general use. WebGPU follows the same concepts, but with a simpler (higher level) API. With wgpu-py we bring WebGPU to Python.

Technically speaking, wgpu-py is a wrapper for wgpu-native, exposing its functionality with a Pythonic API closely resembling the WebGPU spec.

Installation

pip install wgpu glfw

Linux users should make sure that pip >= 20.3. That should do the trick on most systems. See getting started for details.

Usage

Also see the online documentation and the examples.

The full API is accessible via the main namespace:

import wgpu

To render to the screen you can use a variety of GUI toolkits:

# The auto backend selects either the glfw, qt or jupyter backend
from wgpu.gui.auto import WgpuCanvas, run, call_later

# Visualizations can be embedded as a widget in a Qt application.
# Import PySide6, PyQt6, PySide2 or PyQt5 before running the line below.
# The code will detect and use the library that is imported.
from wgpu.gui.qt import WgpuCanvas

# Visualizations can be embedded as a widget in a wx application.
from wgpu.gui.wx import WgpuCanvas

Some functions in the original wgpu-native API are async. In the Python API, the default functions are all sync (blocking), making things easy for general use. Async versions of these functions are available, so wgpu can also work well with Asyncio or Trio.

License

This code is distributed under the 2-clause BSD license.

Projects using wgpu-py

  • pygfx - A python render engine running on wgpu.
  • shadertoy - Shadertoy implementation using wgpu-py.
  • tinygrad - deep learning framework
  • fastplotlib - A fast plotting library
  • xdsl - A Python Compiler Design Toolkit (optional wgpu interpreter)

Developers

  • Clone the repo.
  • Install devtools using pip install -e .[dev].
  • Using pip install -e . will also download the upstream wgpu-native binaries.
    • You can use python tools/download_wgpu_native.py when needed.
    • Or point the WGPU_LIB_PATH environment variable to a custom build of wgpu-native.
  • Use ruff format to apply autoformatting.
  • Use ruff check to check for linting errors.
  • Optionally, if you install pre-commit hooks with pre-commit install, lint fixes and formatting will be automatically applied on git commit.

Updating to a later version of WebGPU or wgpu-native

To update to upstream changes, we use a combination of automatic code generation and manual updating. See the codegen utility for more information.

Testing

The test suite is divided into multiple parts:

  • pytest -v tests runs the unit tests.
  • pytest -v examples tests the examples.
  • pytest -v wgpu/__pyinstaller tests if wgpu is properly supported by pyinstaller.
  • pytest -v codegen tests the code that autogenerates the API.
  • pytest -v tests_mem tests against memoryleaks.

There are two types of tests for examples included:

Type 1: Checking if examples can run

When running the test suite, pytest will run every example in a subprocess, to see if it can run and exit cleanly. You can opt out of this mechanism by including the comment # run_example = false in the module.

Type 2: Checking if examples output an image

You can also (independently) opt-in to output testing for examples, by including the comment # test_example = true in the module. Output testing means the test suite will attempt to import the canvas instance global from your example, and call it to see if an image is produced.

To support this type of testing, ensure the following requirements are met:

  • The WgpuCanvas class is imported from the wgpu.gui.auto module.
  • The canvas instance is exposed as a global in the module.
  • A rendering callback has been registered with canvas.request_draw(fn).

Reference screenshots are stored in the examples/screenshots folder, the test suite will compare the rendered image with the reference.

Note: this step will be skipped when not running on CI. Since images will have subtle differences depending on the system on which they are rendered, that would make the tests unreliable.

For every test that fails on screenshot verification, diffs will be generated for the rgb and alpha channels and made available in the examples/screenshots/diffs folder. On CI, the examples/screenshots folder will be published as a build artifact so you can download and inspect the differences.

If you want to update the reference screenshot for a given example, you can grab those from the build artifacts as well and commit them to your branch.

Testing Locally

Testing locally is possible, however pixel perfect results will differ from those on the CIs due to discrepencies in hardware, and driver (we use llvmpipe) versions.

On linux, it is possible to force the usage of LLVMPIPE in the test suite and compare the generated results of screenshots. Beware, the results on your machine may differ to those on the CI. We always include the CI screenshots in the test suite to improve the repeatability of the tests.

If you have access to a linux machine with llvmpipe installed, you may run the example pixel comparison testing by setting the WGPUPY_WGPU_ADAPTER_NAME environment variable appropriately. For example

WGPUPY_WGPU_ADAPTER_NAME=llvmpipe pytest -v examples/

The WGPUPY_WGPU_ADAPTER_NAME variable is modeled after the https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables and should only be used for testing the wgpu-py library itself. It is not part of the supported wgpu-py interface.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wgpu-0.23.0.tar.gz (169.4 kB view details)

Uploaded Source

Built Distributions

wgpu-0.23.0-py3-none-win_arm64.whl (3.0 MB view details)

Uploaded Python 3Windows ARM64

wgpu-0.23.0-py3-none-win_amd64.whl (3.2 MB view details)

Uploaded Python 3Windows x86-64

wgpu-0.23.0-py3-none-win32.whl (3.0 MB view details)

Uploaded Python 3Windows x86

wgpu-0.23.0-py3-none-manylinux_2_28_x86_64.whl (3.4 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

wgpu-0.23.0-py3-none-manylinux_2_28_aarch64.whl (3.3 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

wgpu-0.23.0-py3-none-macosx_11_0_arm64.whl (2.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

wgpu-0.23.0-py3-none-macosx_10_9_x86_64.whl (2.7 MB view details)

Uploaded Python 3macOS 10.9+ x86-64

File details

Details for the file wgpu-0.23.0.tar.gz.

File metadata

  • Download URL: wgpu-0.23.0.tar.gz
  • Upload date:
  • Size: 169.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for wgpu-0.23.0.tar.gz
Algorithm Hash digest
SHA256 62be1fbd08295f618d4aaca6c288eea446f532f13218b9545af07fe48b9068c4
MD5 4542b349a89fea894c4bbe6233832bd0
BLAKE2b-256 b9f6a3deef47adece9731a915d9fede3102e0e49eefb9b226888ba4c2a952e3c

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: wgpu-0.23.0-py3-none-win_arm64.whl
  • Upload date:
  • Size: 3.0 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for wgpu-0.23.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 50de0fc9fac86394ca1fb7edfdd02e3d5a66661d658aabc1f32a2172ff9c219e
MD5 2649da7cdbd41e3bce38164dbace2a18
BLAKE2b-256 32c1e7f974646e4c3bb58fecc10d8abdbacba3ceb20f6143d1f0c0312fd08049

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: wgpu-0.23.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.2 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for wgpu-0.23.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 543225ee1da92c1dcfc40f3074a9640c55bc84be70c9efccabfe762213f576bd
MD5 26a5c376c69678fb14117816385d9ded
BLAKE2b-256 4ddb9bbae2c1e036f9d87c28da9b66f87acc459a22f3706fdb61484ebf3dbded

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-win32.whl.

File metadata

  • Download URL: wgpu-0.23.0-py3-none-win32.whl
  • Upload date:
  • Size: 3.0 MB
  • Tags: Python 3, Windows x86
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for wgpu-0.23.0-py3-none-win32.whl
Algorithm Hash digest
SHA256 b622c133532584aea425517a2a829d3f74de0cb9c4401c2ec31136713cfda784
MD5 12a2dccce68d17ae340a963e0330795e
BLAKE2b-256 6de00a27e989050d42edd9a72cf7bbff47595374e3948805830a8e6e2a1f110c

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for wgpu-0.23.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 22374e541edbbfc2cffbd70d62564e681d5a9a2e13661e36477f0ffd0030beb5
MD5 6cf7247a4790a96a3a563179042eb1f9
BLAKE2b-256 5e3e1df0c9e82d2709adf858d614f1d4356b5a40343338ce297bc524db2dfa02

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for wgpu-0.23.0-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 eb998b0cdfc60bb7066868ba9e1326081269a99da38a257846c07a6d721b0650
MD5 74d9394e4424e0511a7199cd2caba135
BLAKE2b-256 b91fcc724db3a7bba4d5b4cc9469070b8d35a506800fd1431255eea251a35975

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: wgpu-0.23.0-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 2.6 MB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for wgpu-0.23.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 10859c3e723b8f5364fd58a149d114e9dcb0c85ada1ec9d190179e55d1ea3645
MD5 ea67a52292e414d5914fc9a874005275
BLAKE2b-256 72ec238995573e6adf918df1e19a33c9b7f5034223f8dcb2ba34edfd4674dee9

See more details on using hashes here.

File details

Details for the file wgpu-0.23.0-py3-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for wgpu-0.23.0-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 bcc1185c3410be4e7d1c6b742637b8560d1589c97bec4791859107d866bcd115
MD5 02568f0a6a6a583a5d9d2a67e2f6bbcc
BLAKE2b-256 c53d65cb82b227159f23d418b435ae93a8b85b4c9c91a1d621e4032f6d5a25a2

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page