py-Vwayland

Spawn virtual Wayland compositors from Python, run GUI programs inside them, capture their screens, and inject mouse/keyboard events.

No desktop environment required: one program per compositor, fullscreen. The compositor is written in Rust (Smithay) and bundled into the package, so no system compositor or display server is needed (in headless mode).

import vwayland

with vwayland.spawn(width=1280, height=720, headless=True) as comp:
    comp.launch("my-gui-app")
    img = comp.screenshot()
    img.save("screen.png")
    comp.click(100, 200)
    comp.type_text("hello")
    comp.key("enter")

Installation

$ pip install py-vwayland

The wheel bundles the compositor binary and its native libraries, so headless mode works out of the box on any x86_64 Linux with glibc ≥ 2.28 — no display server, GPU, or extra packages required. For screenshot().to_pil():

$ pip install py-vwayland[pillow]

Quick sanity check:

$ python3 -c "import vwayland; c = vwayland.spawn(); print(c.info()); c.kill()"

Building from source and platform details (windowed mode, musl, other architectures): see docs/installation.md.

Key features

• Create/list/terminate compositors (spawn, list, kill)
• Open/close a program inside a compositor (launch, close_app)
• Resize the screen (resize)
• Switch between headless and windowed mode (set_headless)
• Capture the screen (screenshot → PNG)
• Mouse move/click/drag/scroll (move_to, click, drag, scroll)
• Keyboard input (key, combo, type_text — any language/Unicode typing)
• Clipboard and Unicode text paste (clipboard_get/clipboard_set/clipboard_clear, paste_text)

Documentation

See docs/ for full documentation.

• Overview and motivation
• Installation and compatibility
• Python API reference
• CLI reference
• Architecture and IPC protocol

License

Apache License 2.0 — see LICENSE.