This release is a pre-release and may not be stable for production use.
Headless Kivy
Provides utilities to render Kivy applications headlessly. It calls a callback whenever something has changed in the framebuffer in a locality.
It can be used to render the Kivy application on a custom display like an SPI display, it provides tools for local updates, limiting the bandwidth and limiting the fps based on the spec of the display.
It can also be used in test environments with it tools for snapshot testing.
You can control the orientation of the display and flipping the display horizontally and vertically.
The renderer is optimized to not schedule a render when nothing has changed since the last rendered frame, by default it divides the screen into tiles and checks each tile for changes separately.
It can be configured to use double buffering, so that the next frame is generated while the last frame is being transmitted to the display.
You can have multiple instances of the headless renderer in the same application, each works as a portal to your display (or multiple different displays).
📦 Installation
pip install headless-kivy
To use its test tools, you can install it with the following command:
pip install headless-kivy[test]
🛠 Usage
-
Call setup_headless() before inheriting the
HeadlessWidgetclass for the root widget of your application, and provide the optional parameters as needed. For example (these are all default values, you only need to provide the ones you want to change):setup_headless( width=240, height=240, bandwidth_limit=1000000, # number of pixels per second bandwidth_limit_window=.1, # allow bandwidth_limit x bandwidth_limit_window pixels to be transmitted in bandwidth_limit_window seconds bandwidth_limit_overhead=1000, # each draw command, regardless of the size, has equivalent of this many pixels of cost in bandwidth is_debug_mode=False, rotation=1, # gets multiplied by 90 degrees flip_horizontal=True, double_buffering=True, # let headless kivy generate the next frame while the previous callback is still running )
-
Inherit the
HeadlessWidgetclass for the root widget of your Kivy application. For example:class FboFloatLayout(FloatLayout, HeadlessWidget): pass
-
Run the Kivy app as you normally would.
Checkout Ubo App to see a sample implementation.
⚙️ Parameters
These parameters can be set to control the behavior of headless kivy:
callback
A callback function that will be called when the screen data changes. It should have this signature:
def render(
*,
rectangle: tuple[int, int, int, int],
data: NDArray[np.uint8],
data_hash: int,
last_render_thread: Thread,
) -> None: ...
rectangle is a tuple with the coordinates and size of the changed area in the
(x, y, width, height) format.
data is a numpy array with the screen RGB data in the uint8 format. So its
dimensions are (width, height, 3).
data_hash is probably not very useful for most cases, it is mostly for logging
and debugging purposes.
It always runs in a new thread, the previous thread is provided so that it can call
its join if desired.
bandwidth_limit
Maximum bandwidth usage in pixels per second, no limit if set to 0.
bandwidth_limit_window
Length of the time window in seconds to check the bandwidth limit.
bandwidth_limit_overhead
The overhead of each draw command in pixels, regardless of its size.
width
The width of the display in pixels.
height
The height of the display in pixels.
is_debug_mode
If set to True, the application will print debug information, including FPS.
double_buffering
Is set to True, it will let Kivy generate the next frame while sending the last
frame to the display.
rotation
The rotation of the display. It will be multiplied by 90 degrees.
flip_horizontal
If set to True, it will flip the display horizontally.
flip_vertical
If set to True, it will flip the display vertically.
🤝 Contributing
You need to have uv installed on your machine.
To install the required dependencies, run the following command in the root directory of the project:
uv sync
⚠️ Important Note
This project has only been tested with the ST7789 SPI display module. Other display modules might not be compatible or may require changing the parameters or even modifications to the code.
🔒 License
This project is released under the Apache-2.0 License. See the LICENSE file for more details.
1 maintainer
Metadata
1 maintainer
Release files for headless-kivy 0.12.4.dev125052810353565798
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| headless_kivy-0.12.4.dev125052810353565798.tar.gz | 16.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| headless_kivy-0.12.4.dev125052810353565798-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 37.0 kB
Release files / headless_kivy-0.12.4.dev125052810353565798.tar.gz
| Download URL | headless_kivy-0.12.4.dev125052810353565798.tar.gz |
|---|---|
| Size | 16.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1abf519a0693f2cd54aba719e215a4c5dc75cf3a60abbbb68b290d6e0e0dbd55
|
|
BLAKE2b-256 checksum How to use checksums |
37e35d75808d69aeb0f58a88384e16a2235ba892f2214730521dcc50dc8e4e41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 28, 2025.
Transparency logRelease files / headless_kivy-0.12.4.dev125052810353565798-py3-none-any.whl
| Download URL | headless_kivy-0.12.4.dev125052810353565798-py3-none-any.whl |
|---|---|
| Size | 20.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
66b8f9c5dc18f52ae83f119882633d2a20c52c7094d8d831ba691563dbea8889
|
|
BLAKE2b-256 checksum How to use checksums |
ae1ad84a30c7919816a8125cff181aed1fa1c40271f43c7f757641c60b5b0490
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 28, 2025.
Transparency log
