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.

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"
`textfield[name^='Search']`	Text field whose name starts with "Search"
`textfield[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 / activate
`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.
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 setup.

License

MIT. All dependencies are permissively licensed (MIT, Apache-2.0, BSD, or similar), enforced via cargo-deny.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xa11y-0.14.0.tar.gz (532.7 kB view details)

Uploaded Sep 9, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

xa11y-0.14.0-cp39-abi3-win_amd64.whl (900.3 kB view details)

Uploaded Sep 9, 2026 CPython 3.9+Windows x86-64

xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Sep 9, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.8 MB view details)

Uploaded Sep 9, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl (1.0 MB view details)

Uploaded Sep 9, 2026 CPython 3.9+macOS 11.0+ ARM64

xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded Sep 9, 2026 CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file xa11y-0.14.0.tar.gz.

File metadata

Download URL: xa11y-0.14.0.tar.gz
Upload date: Sep 9, 2026
Size: 532.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0.tar.gz
Algorithm	Hash digest
SHA256	`35b611fd4a6f131a29cb8967dd24e0fdd0931a1eaeeb5ce86c4ff899ce0804ce`
MD5	`7f0e051522f7d59d8cf407e2f6d22564`
BLAKE2b-256	`a7196f8b7240bab4e8692f739e5a3b23396292201e7a5f477f364a698a072a00`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0.tar.gz:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0.tar.gz
- Subject digest: 35b611fd4a6f131a29cb8967dd24e0fdd0931a1eaeeb5ce86c4ff899ce0804ce
- Sigstore transparency entry: 2771076417
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch

File details

Details for the file xa11y-0.14.0-cp39-abi3-win_amd64.whl.

File metadata

Download URL: xa11y-0.14.0-cp39-abi3-win_amd64.whl
Upload date: Sep 9, 2026
Size: 900.3 kB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`c8431b1234d88e9132270ae15b13a81550bd4ee7045f86c45ed232a68008c990`
MD5	`53af4395ffcb4cc889f2df1df029d333`
BLAKE2b-256	`ce7d19b336718a3304bd9a8636d776c58ab99bc2827d8f989999c11d93128fd5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0-cp39-abi3-win_amd64.whl:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0-cp39-abi3-win_amd64.whl
- Subject digest: c8431b1234d88e9132270ae15b13a81550bd4ee7045f86c45ed232a68008c990
- Sigstore transparency entry: 2771076451
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch

File details

Details for the file xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Sep 9, 2026
Size: 2.8 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`3ad8235b46770bfc98b71467f5862f80aacafde49ed105d7e1d3ccf8e6b4b205`
MD5	`a00ba3d2f2bd5519ba22b1a7512d7294`
BLAKE2b-256	`0a2298ce1d5713d35312102130c00ef14ce74f2d515aac2a664ac334d111949b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 3ad8235b46770bfc98b71467f5862f80aacafde49ed105d7e1d3ccf8e6b4b205
- Sigstore transparency entry: 2771076575
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch

File details

Details for the file xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Sep 9, 2026
Size: 2.8 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`def4f06061e433eeef01886ae55f968cc9b1e2ed854919555d6284704c7f18cb`
MD5	`88e0c1a2c36022b713b623dcff870353`
BLAKE2b-256	`95c24feace44d7445a1fb86e454f97db4572667cee49d44c3c7efee891fb2aae`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: def4f06061e433eeef01886ae55f968cc9b1e2ed854919555d6284704c7f18cb
- Sigstore transparency entry: 2771076538
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch

File details

Details for the file xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Sep 9, 2026
Size: 1.0 MB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`fbf4429bbde7019cef8a80679e3a1cb75e7f111ddbf229d17cd2d5634e6606d8`
MD5	`6c5de0c2702f37571145e4365af4dd88`
BLAKE2b-256	`321368f2dcc5752d569d1006152a78e713a82c81f34c7542073277cded5787c2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: fbf4429bbde7019cef8a80679e3a1cb75e7f111ddbf229d17cd2d5634e6606d8
- Sigstore transparency entry: 2771076601
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch

File details

Details for the file xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl
Upload date: Sep 9, 2026
Size: 1.1 MB
Tags: CPython 3.9+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`9ffd5a8c266221189898a9e337b4d7dcb0f3edd0ff1ea00e701c2bbfe12bcd69`
MD5	`a1be2c97fb0976509ca18e3abc8bd337`
BLAKE2b-256	`877e71cc0508d4040698336744d8f2a27a869d666592e012857bdbe6b319bc31`

See more details on using hashes here.

Provenance

The following attestation bundles were made for xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on xa11y/xa11y

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: xa11y-0.14.0-cp39-abi3-macosx_10_12_x86_64.whl
- Subject digest: 9ffd5a8c266221189898a9e337b4d7dcb0f3edd0ff1ea00e701c2bbfe12bcd69
- Sigstore transparency entry: 2771076495
- Sigstore integration time: Sep 9, 2026
Source repository:
- Permalink: xa11y/xa11y@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/xa11y
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8698e0a1d30baade6520324d0ccbbc7d926f584d
- Trigger Event: workflow_dispatch