xa11y
A Playwright-style library for driving native desktop apps on macOS, Windows, and Linux. Built for end-to-end tests, computer-use agents, and assistive tools.
Use cases: end-to-end desktop testing, computer-use agents, MCP tools, assistive technology.
Documentation | Rust API | Python API | JavaScript API
Quick Example
import xa11y
safari = xa11y.App.by_name("Safari")
# Find elements with CSS-like selectors via locator
for button in safari.locator("button").elements():
print(button.name)
# Interact with elements via locator (re-resolves every call)
safari.locator("button[name='Submit']").press()
safari.locator("text_field[name^='Search']").set_value("hello world")
Installation
Python
pip install xa11y
Requires Python 3.9+. Pre-built wheels available for Linux, macOS, and Windows.
For pytest suites, pytest-xa11y adds
fixtures that launch the app under test, capability markers that skip what the
machine cannot do, and the accessibility tree on every failure:
pip install pytest-xa11y
On macOS, grant your terminal two permissions in System Settings > Privacy & Security:
- Accessibility, required for all accessibility API access. On macOS 27 and newer, grant it in Device Control and Data Access.
- Screen & System Audio Recording (macOS 26+), required to read window content. Without it, only menu bars are visible.
Restart your terminal after changing permissions.
On Linux, AT-SPI2 must be running (the default on GNOME and most desktop environments). Nothing else to grant.
Windows works as installed.
Selector Syntax
Query accessibility trees with CSS-like selectors:
| Pattern | Meaning |
|---|---|
button |
Elements with role Button |
button[name='OK'] |
Button named exactly "OK" |
text_field[name^='Search'] |
Text field whose name starts with "Search" |
text_field[name*='email'] |
Text field whose name contains "email" |
group > button |
Buttons that are direct children of a group |
window button |
Buttons anywhere inside a window |
button:nth(2) |
The 2nd button match |
Supported Actions
| Action | Description |
|---|---|
press |
Click / invoke |
focus / blur |
Move or remove keyboard focus |
toggle |
Toggle a checkbox or switch |
expand / collapse |
Expand or collapse a disclosure |
select |
Select an item |
set_value |
Set a text field's value |
type_text |
Type text into an element |
increment / decrement |
Adjust a slider or stepper |
show_menu |
Open a context menu |
Platform Support
| Platform | Backend |
|---|---|
| macOS | AXUIElement |
| Linux | AT-SPI2 (D-Bus) |
| Windows | UI Automation |
Ecosystem
- strands-xa11y packages xa11y as a desktop-control tool for Strands, AWS's open-source SDK for building AI agents. One tool gives an agent the accessibility tree and the actions on it; a read-only variant covers agents that observe and never act.
pip install strands-xa11y(requires Python 3.10+). - agent-desktop is a CLI built on xa11y for AI agents that read and control desktops.
Contributing
git clone https://github.com/xa11y/xa11y && cd xa11y
cargo build --workspace
cargo xtask check # fmt, lint, test, python bindings
See the development docs for architecture and testing strategy.
License
MIT. All dependencies are permissively licensed (MIT, Apache-2.0, BSD, or similar), enforced via cargo-deny.
1 maintainer
Metadata
1 maintainer
Release files for xa11y 0.15.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| xa11y-0.15.1.tar.gz | 675.4 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| xa11y-0.15.1-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| xa11y-0.15.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| xa11y-0.15.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| xa11y-0.15.1-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
| xa11y-0.15.1-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 10.0 MB
Release files / xa11y-0.15.1.tar.gz
| Download URL | xa11y-0.15.1.tar.gz |
|---|---|
| Size | 675.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
458d32687e6bc78417e274dc5c1f8d352673243312b987ba6f829deef30d4098
|
|
BLAKE2b-256 checksum How to use checksums |
b94d5ebe82f3acb5bae4bc24891dc78455b070448c29de06491a529adef86b7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / xa11y-0.15.1-cp39-abi3-win_amd64.whl
| Download URL | xa11y-0.15.1-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
503d5589b82a66877b53088b7a9bd403d4f3cdf133429f1c770b47e348af0961
|
|
BLAKE2b-256 checksum How to use checksums |
a66c2f0368e8a2e3cd61854c8e02a9fa12782dea355bddb79ac870d58add1ff2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / xa11y-0.15.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | xa11y-0.15.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5387c0450db693cdd2419bb2c661f54f6d373cd9ba946fb5a17558ab6645f9e2
|
|
BLAKE2b-256 checksum How to use checksums |
c303aae0ca4a00aebe98a2a8e05fcac4ed521c5d41e6658b51eb7df3146a6fb7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / xa11y-0.15.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | xa11y-0.15.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
f8571e8ab6d403472c18e490d7756a33a57c039f01642418c29072745f2d1938
|
|
BLAKE2b-256 checksum How to use checksums |
997b923d55674d36799f70d89d9d26b23b49bf28e9074610a81f1d6106ceac63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / xa11y-0.15.1-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | xa11y-0.15.1-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4214e478d7f44337e7e1ba9658748bd3284f53801ef8386455f06b5c30082898
|
|
BLAKE2b-256 checksum How to use checksums |
b5ce6e5b938c6f3c865bfc997a9e781d9f8a13925d55560881a9591230254be7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / xa11y-0.15.1-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | xa11y-0.15.1-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
bd9193071de0237ec39b07d46e54829fbecc7d47ec2ad611bd19d6017f1df88f
|
|
BLAKE2b-256 checksum How to use checksums |
3fb3f4835c944c10539f1fedac640ab6e100ebe4574f776974baf9c73ba43eaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency log
