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.

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.19.0.tar.gz (147.8 kB view details)

Uploaded Source

Built Distributions

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

Uploaded Python 3 Windows ARM64

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

Uploaded Python 3 Windows x86-64

wgpu-0.19.0-py3-none-win32.whl (2.9 MB view details)

Uploaded Python 3 Windows x86

wgpu-0.19.0-py3-none-manylinux_2_28_x86_64.whl (3.1 MB view details)

Uploaded Python 3 manylinux: glibc 2.28+ x86-64

wgpu-0.19.0-py3-none-manylinux_2_28_aarch64.whl (3.2 MB view details)

Uploaded Python 3 manylinux: glibc 2.28+ ARM64

wgpu-0.19.0-py3-none-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Python 3 macOS 11.0+ ARM64

wgpu-0.19.0-py3-none-macosx_10_9_x86_64.whl (2.3 MB view details)

Uploaded Python 3 macOS 10.9+ x86-64

File details

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

File metadata

  • Download URL: wgpu-0.19.0.tar.gz
  • Upload date:
  • Size: 147.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for wgpu-0.19.0.tar.gz
Algorithm Hash digest
SHA256 c4c5544eb0e4c2297e54fd35538bd51c144221adfb0c012d6b26155e4f19e7ce
MD5 ea09d378b4fd7173709cc076176aedd7
BLAKE2b-256 b0e658e42693b01727bf16c4286ea6097148c74b1e6688f54a4b40c8cc757d5c

See more details on using hashes here.

Provenance

File details

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

File metadata

  • Download URL: wgpu-0.19.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/5.1.1 CPython/3.12.7

File hashes

Hashes for wgpu-0.19.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 0124b1d06e4ac2a8a46a985fb2439833bf15683f7db1bf75ed48098dc7b93d0d
MD5 c96304b60b31f2cc15a1e96f918102d5
BLAKE2b-256 dbbd74dfcf2b221754e6616f5d7a0c4e2250743fdb10ee33b59d5490d4a8ed73

See more details on using hashes here.

Provenance

File details

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

File metadata

  • Download URL: wgpu-0.19.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/5.1.1 CPython/3.12.7

File hashes

Hashes for wgpu-0.19.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 6bb34ccb53758690246aadd38b03416e22d697c130bbe35611731ba198be2008
MD5 8f290d0baa184e3de72bbf85ee0da3c6
BLAKE2b-256 6515b96995a415c51ee37a83107d558b57f21e393f4b58c2fe319d25a04abb1f

See more details on using hashes here.

Provenance

File details

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

File metadata

  • Download URL: wgpu-0.19.0-py3-none-win32.whl
  • Upload date:
  • Size: 2.9 MB
  • Tags: Python 3, Windows x86
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for wgpu-0.19.0-py3-none-win32.whl
Algorithm Hash digest
SHA256 10adddab1cd70eee01bc53ac9a84b915fae1f23b02015a0433a6eb20021801d6
MD5 dfa7d2b6a7bdff852b44c6fbad0a4d22
BLAKE2b-256 8833ebcd1cb12031103934dbde81e0e572724246e5105d7ed28f9d2524948d87

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for wgpu-0.19.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4ed55e37242ae498213dda14ac381d33b82702714346e20a2c323cc427bb87ae
MD5 9993310e1b18e8faeac572c72577464c
BLAKE2b-256 09e8d1c177ae009fa607777634d5a2b51a89ff043e36d7b85a40d9faefb1927b

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for wgpu-0.19.0-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 b32c5f5196d9aa5a0eee79fd7ad6823725e942fe6f4e24619a194687b5959289
MD5 7a44f6946b3c8140ff11e180d32c2352
BLAKE2b-256 c358ceb770d562a3c5910d039130ee71da3b6b30b70e6213d4b408bd59825e31

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for wgpu-0.19.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 08d5c5f9d7868cf016b5e1bd15316d93e1f306433b5f5e69a9e62a6b862b2444
MD5 ff63dc6c38a0efc80f31009db4972258
BLAKE2b-256 87d97e065b95743211f71534bee2e26ca409ac7c3822153d4878b62f1e437054

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for wgpu-0.19.0-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 d17ab5c63509738661f3a2d140e2c64bb9fad416298bfd28bc8517cd22b3c297
MD5 fb5c60b6120cda1314e84cd25aa980ae
BLAKE2b-256 ebee4ac7612579c2287207d0a3f9aefd2e8541e8fd1f98e98427973ba9a6c3b2

See more details on using hashes here.

Provenance

Supported by

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