[](https://github.com/pygfx/wgpu-py/actions)
[](https://wgpu-py.readthedocs.io)
[](https://badge.fury.io/py/wgpu)
# wgpu-py
A Python implementation of WebGPU - the next generation GPU API.
<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/cube.png' />
<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/triangle_auto.png' />
## Introduction
In short, this is a Python lib wrapping
[wgpu-native](https://github.com/gfx-rs/wgpu) and exposing it with a Pythonic
API similar to the [WebGPU spec](https://gpuweb.github.io/gpuweb/).
The OpenGL API is old and showing it's cracks. New API's like Vulkan, Metal and
DX12 provide a modern way to control the GPU, but these API's are too low-level
for general use. The WebGPU API follows the same concepts, but with a simpler
(higher level) spelling. The Python `wgpu` library brings the WebGPU API to
Python.
To get an idea of what this API looks like have a look at
[triangle.py](https://github.com/pygfx/wgpu-py/blob/main/examples/triangle.py)
and the other [examples](https://github.com/pygfx/wgpu-py/blob/main/examples/).
## Status
> **Note**
>
> The wgpu-API has not settled yet, use with care!
* Coverage of the WebGPU spec is complete enough to build e.g.
[pygfx](https://github.com/pygfx/pygfx).
* Test coverage of the API is close to 100%.
* Support for Windows, Linux, and MacOS (Intel and M1).
* Until WebGPU settles as a standard, its specification may change, and with
that our API will probably too. Check the [changelog](CHANGELOG.md) when you
upgrade!
## 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](https://wgpu-py.readthedocs.io/en/stable/start.html)
for details.
## Usage
Also see the [online documentation](https://wgpu-py.readthedocs.io) and the [examples](https://github.com/pygfx/wgpu-py/tree/main/examples).
The full API is accessable via the main namespace:
```py
import wgpu
```
To render to the screen you can use a variety of GUI toolkits:
```py
# 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](https://github.com/pygfx/pygfx) - A python render engine running on wgpu.
* [shadertoy](https://github.com/pygfx/shadertoy) - Shadertoy implementation using wgpu-py.
* [tinygrad](https://github.com/tinygrad/tinygrad) - deep learning framework
* [fastplotlib](https://github.com/fastplotlib/fastplotlib) - A fast plotting library
* [xdsl](https://github.com/xdslproject/xdsl) - A Python Compiler Design Toolkit (optional wgpu interpreter)
## Developers
* Clone the repo.
* Install devtools using `pip install -r dev-requirements.txt` (you can replace
`pip` with `pipenv` to install to a virtualenv).
* Install wgpu-py in editable mode by running `pip install -e .`, this will also
install runtime dependencies as needed.
* Run `python download-wgpu-native.py` to download the upstream wgpu-native
binaries.
* Or alternatively point the `WGPU_LIB_PATH` environment variable to a custom
build.
* Use `black .` to apply autoformatting.
* Use `flake8 .` to check for flake errors.
* Use `pytest .` to run the tests.
* Use `pip wheel --no-deps .` to build a wheel.
### 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](codegen/README.md)
for more information.
## Testing
The test suite is divided into multiple parts:
* `pytest -v tests` runs the core unit tests.
* `pytest -v examples` tests the examples.
* `pytest -v wgpu/__pyinstaller` tests if wgpu is properly supported by
pyinstaller.
* `pytest -v codegen` lints the generated binding code.
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/pygfx/wgpu-py",
"name": "wgpu",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": null,
"author": "Almar Klein",
"author_email": "almar.klein@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/00/a1/b32c03215cb711409a827d32de5dc02248c65cba8f99ffab72836d4615f2/wgpu-0.15.1.tar.gz",
"platform": null,
"description": "[](https://github.com/pygfx/wgpu-py/actions)\n[](https://wgpu-py.readthedocs.io)\n[](https://badge.fury.io/py/wgpu)\n\n# wgpu-py\n\nA Python implementation of WebGPU - the next generation GPU API.\n\n<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/cube.png' />\n<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/triangle_auto.png' />\n\n\n## Introduction\n\nIn short, this is a Python lib wrapping\n[wgpu-native](https://github.com/gfx-rs/wgpu) and exposing it with a Pythonic\nAPI similar to the [WebGPU spec](https://gpuweb.github.io/gpuweb/).\n\nThe OpenGL API is old and showing it's cracks. New API's like Vulkan, Metal and\nDX12 provide a modern way to control the GPU, but these API's are too low-level\nfor general use. The WebGPU API follows the same concepts, but with a simpler\n(higher level) spelling. The Python `wgpu` library brings the WebGPU API to\nPython.\n\nTo get an idea of what this API looks like have a look at\n[triangle.py](https://github.com/pygfx/wgpu-py/blob/main/examples/triangle.py)\nand the other [examples](https://github.com/pygfx/wgpu-py/blob/main/examples/).\n\n\n## Status\n\n> **Note**\n>\n> The wgpu-API has not settled yet, use with care!\n\n* Coverage of the WebGPU spec is complete enough to build e.g.\n [pygfx](https://github.com/pygfx/pygfx).\n* Test coverage of the API is close to 100%.\n* Support for Windows, Linux, and MacOS (Intel and M1).\n* Until WebGPU settles as a standard, its specification may change, and with\n that our API will probably too. Check the [changelog](CHANGELOG.md) when you\n upgrade!\n\n\n## Installation\n\n\n```\npip install wgpu glfw\n```\n\nLinux users should make sure that **pip >= 20.3**. That should do the\ntrick on most systems. See [getting started](https://wgpu-py.readthedocs.io/en/stable/start.html)\nfor details.\n\n\n## Usage\n\nAlso see the [online documentation](https://wgpu-py.readthedocs.io) and the [examples](https://github.com/pygfx/wgpu-py/tree/main/examples).\n\nThe full API is accessable via the main namespace:\n```py\nimport wgpu\n```\n\nTo render to the screen you can use a variety of GUI toolkits:\n\n```py\n# The auto backend selects either the glfw, qt or jupyter backend\nfrom wgpu.gui.auto import WgpuCanvas, run, call_later\n\n# Visualizations can be embedded as a widget in a Qt application.\n# Import PySide6, PyQt6, PySide2 or PyQt5 before running the line below.\n# The code will detect and use the library that is imported.\nfrom wgpu.gui.qt import WgpuCanvas\n\n# Visualizations can be embedded as a widget in a wx application.\nfrom wgpu.gui.wx import WgpuCanvas\n```\n\nSome functions in the original `wgpu-native` API are async. In the Python API,\nthe default functions are all sync (blocking), making things easy for general use.\nAsync versions of these functions are available, so wgpu can also work\nwell with Asyncio or Trio.\n\n\n## License\n\nThis code is distributed under the 2-clause BSD license.\n\n## Projects using `wgpu-py`\n\n* [pygfx](https://github.com/pygfx/pygfx) - A python render engine running on wgpu.\n* [shadertoy](https://github.com/pygfx/shadertoy) - Shadertoy implementation using wgpu-py.\n* [tinygrad](https://github.com/tinygrad/tinygrad) - deep learning framework\n* [fastplotlib](https://github.com/fastplotlib/fastplotlib) - A fast plotting library\n* [xdsl](https://github.com/xdslproject/xdsl) - A Python Compiler Design Toolkit (optional wgpu interpreter)\n\n## Developers\n\n* Clone the repo.\n* Install devtools using `pip install -r dev-requirements.txt` (you can replace\n `pip` with `pipenv` to install to a virtualenv).\n* Install wgpu-py in editable mode by running `pip install -e .`, this will also\n install runtime dependencies as needed.\n* Run `python download-wgpu-native.py` to download the upstream wgpu-native\n binaries.\n * Or alternatively point the `WGPU_LIB_PATH` environment variable to a custom\n build.\n* Use `black .` to apply autoformatting.\n* Use `flake8 .` to check for flake errors.\n* Use `pytest .` to run the tests.\n* Use `pip wheel --no-deps .` to build a wheel.\n\n\n### Updating to a later version of WebGPU or wgpu-native\n\nTo update to upstream changes, we use a combination of automatic code\ngeneration and manual updating. See [the codegen utility](codegen/README.md)\nfor more information.\n\n\n## Testing\n\nThe test suite is divided into multiple parts:\n\n* `pytest -v tests` runs the core unit tests.\n* `pytest -v examples` tests the examples.\n* `pytest -v wgpu/__pyinstaller` tests if wgpu is properly supported by\n pyinstaller.\n* `pytest -v codegen` lints the generated binding code.\n\nThere are two types of tests for examples included:\n\n### Type 1: Checking if examples can run\n\nWhen running the test suite, pytest will run every example in a subprocess, to\nsee if it can run and exit cleanly. You can opt out of this mechanism by\nincluding the comment `# run_example = false` in the module.\n\n### Type 2: Checking if examples output an image\n\nYou can also (independently) opt-in to output testing for examples, by including\nthe comment `# test_example = true` in the module. Output testing means the test\nsuite will attempt to import the `canvas` instance global from your example, and\ncall it to see if an image is produced.\n\nTo support this type of testing, ensure the following requirements are met:\n\n* The `WgpuCanvas` class is imported from the `wgpu.gui.auto` module.\n* The `canvas` instance is exposed as a global in the module.\n* A rendering callback has been registered with `canvas.request_draw(fn)`.\n\nReference screenshots are stored in the `examples/screenshots` folder, the test\nsuite will compare the rendered image with the reference.\n\nNote: this step will be skipped when not running on CI. Since images will have\nsubtle differences depending on the system on which they are rendered, that\nwould make the tests unreliable.\n\nFor every test that fails on screenshot verification, diffs will be generated\nfor the rgb and alpha channels and made available in the\n`examples/screenshots/diffs` folder. On CI, the `examples/screenshots` folder\nwill be published as a build artifact so you can download and inspect the\ndifferences.\n\nIf you want to update the reference screenshot for a given example, you can grab\nthose from the build artifacts as well and commit them to your branch.\n",
"bugtrack_url": null,
"license": "BSD 2-Clause",
"summary": "Next generation GPU API for Python",
"version": "0.15.1",
"project_urls": {
"Homepage": "https://github.com/pygfx/wgpu-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b79ae3c168fb50cf38796598534f7eef9f7067a69ddb8bbf5453b0c15565427a",
"md5": "7f740d3fa8e781b7d3068ea03b55334e",
"sha256": "6b1a9430c3103e3cf71e5a69d1de37a899b7278806b5890daa30c78f7735df4b"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "7f740d3fa8e781b7d3068ea03b55334e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 2045099,
"upload_time": "2024-03-30T20:45:20",
"upload_time_iso_8601": "2024-03-30T20:45:20.434088Z",
"url": "https://files.pythonhosted.org/packages/b7/9a/e3c168fb50cf38796598534f7eef9f7067a69ddb8bbf5453b0c15565427a/wgpu-0.15.1-py3-none-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ca0594b33255fd7da4870db65f07a1a619103761131c46f1a04acc6d8e019b2",
"md5": "df9b44f3a58dc4067144229e40e1575b",
"sha256": "e3b4fae125dc5de4a864f689ba78b76158a42ec999526c40a53ecbb918ed81c4"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "df9b44f3a58dc4067144229e40e1575b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 1976688,
"upload_time": "2024-03-30T20:45:22",
"upload_time_iso_8601": "2024-03-30T20:45:22.991226Z",
"url": "https://files.pythonhosted.org/packages/2c/a0/594b33255fd7da4870db65f07a1a619103761131c46f1a04acc6d8e019b2/wgpu-0.15.1-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f3039dec2a8e3ac5d5cdfdd1db2e8b9d1c51c4d9bc8515f65c6bc3bb6328192d",
"md5": "664f2f7ce2009995ad0de8092222799b",
"sha256": "c6a7fd827582086c8eaca14d9b8a841adb3340fe8f5ad97d0818c3e4c0de7eaf"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "664f2f7ce2009995ad0de8092222799b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 3624970,
"upload_time": "2024-03-30T20:45:25",
"upload_time_iso_8601": "2024-03-30T20:45:25.225490Z",
"url": "https://files.pythonhosted.org/packages/f3/03/9dec2a8e3ac5d5cdfdd1db2e8b9d1c51c4d9bc8515f65c6bc3bb6328192d/wgpu-0.15.1-py3-none-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "486a0e10c73cf618f08b6de47293b2286e9169b014b56e65611d04b93df1b902",
"md5": "b32266f332b9130618f70c58d178fd60",
"sha256": "ec969e813f82da8d480ed0811990172c9a298210930e33494d2858a62107bf88"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "b32266f332b9130618f70c58d178fd60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 3545676,
"upload_time": "2024-03-30T20:45:27",
"upload_time_iso_8601": "2024-03-30T20:45:27.059346Z",
"url": "https://files.pythonhosted.org/packages/48/6a/0e10c73cf618f08b6de47293b2286e9169b014b56e65611d04b93df1b902/wgpu-0.15.1-py3-none-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fb5be30f015b4f3aeb676a1728e16d140bffc36d9d90c35a9954b274e7a2cc31",
"md5": "d5dd70c5d95a20d2c81176a4602b56ab",
"sha256": "3c2179d810a40aa3f13484d0332616e5deb78cf2e07b53d23b14a19c261adcbc"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-win32.whl",
"has_sig": false,
"md5_digest": "d5dd70c5d95a20d2c81176a4602b56ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 2491318,
"upload_time": "2024-03-30T20:45:28",
"upload_time_iso_8601": "2024-03-30T20:45:28.623316Z",
"url": "https://files.pythonhosted.org/packages/fb/5b/e30f015b4f3aeb676a1728e16d140bffc36d9d90c35a9954b274e7a2cc31/wgpu-0.15.1-py3-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4fe3422d0df9d1251e6641aa689a14afbeb168ad49888f269f5e3cd9c170f06d",
"md5": "9d8c6bebac91ad7c0860b2f5cc15ae70",
"sha256": "1ba03baeb4635d52539f1ed54feedd220618b80c24b819f71435de17b5318c5a"
},
"downloads": -1,
"filename": "wgpu-0.15.1-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "9d8c6bebac91ad7c0860b2f5cc15ae70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 2739395,
"upload_time": "2024-03-30T20:45:30",
"upload_time_iso_8601": "2024-03-30T20:45:30.336154Z",
"url": "https://files.pythonhosted.org/packages/4f/e3/422d0df9d1251e6641aa689a14afbeb168ad49888f269f5e3cd9c170f06d/wgpu-0.15.1-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00a1b32c03215cb711409a827d32de5dc02248c65cba8f99ffab72836d4615f2",
"md5": "a245daaad65a4c53529917ee217f46c9",
"sha256": "6d018048f2ca33442a5fe85fc21788f8ea87948c8c9e63fd5cbc6cc03aa7a86f"
},
"downloads": -1,
"filename": "wgpu-0.15.1.tar.gz",
"has_sig": false,
"md5_digest": "a245daaad65a4c53529917ee217f46c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 155121,
"upload_time": "2024-03-30T20:45:31",
"upload_time_iso_8601": "2024-03-30T20:45:31.835397Z",
"url": "https://files.pythonhosted.org/packages/00/a1/b32c03215cb711409a827d32de5dc02248c65cba8f99ffab72836d4615f2/wgpu-0.15.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-30 20:45:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pygfx",
"github_project": "wgpu-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wgpu"
}
JSON
