Registry / testing / uiautomator2

uiautomator2

JSON →
library3.5.2pypypi✓ verified 89d ago

uiautomator2 is a Python wrapper for Google's UiAutomator test framework, enabling robust UI automation for Android devices. It simplifies interacting with Android applications, performing actions like clicking, typing, scrolling, and getting device information. The current stable version is 3.5.0, with frequent patch releases addressing bug fixes and minor enhancements. It requires Python 3.8 to 3.11.

pip install uiautomator2
INSTALL
IMPORT
SIG · UIAUTOMATOR2
U
uiautomator2
testingpythonv3.5.2
Install
3.8s avg
Import
774ms
Disk
63MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v3.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.817s · 61.8MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 3.8s · import 0.730s · 69MB
63MB installed
● package 63MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

uiautomator2
✓ import uiautomator2 as u2
✗ from uiautomator2 import connect
While 'from uiautomator2 import connect' works, 'import uiautomator2 as u2' is the idiomatic and recommended way to use the library, providing access to all methods through the 'u2' alias.

This quickstart demonstrates how to connect to an Android device using `uiautomator2`, retrieve device information, take a screenshot, press the home button, and dump the UI hierarchy. Remember to run `u2 init` on your device first to set up the necessary server applications.

import uiautomator2 as u2 import os # Connect to a device. You can specify a serial (e.g., 'emulator-5554') # or an IP address (e.g., '192.168.1.100'). If no argument is given, # it tries to connect to the first available device via ADB. # Ensure 'adb devices' shows your device and 'u2 init' has been run on the device. # Example for connecting to a specific IP, fallback to default DEVICE_ADDRESS = os.environ.get('U2_DEVICE_ADDRESS', None) try: if DEVICE_ADDRESS: d = u2.connect(DEVICE_ADDRESS) else: d = u2.connect() # Connects to the default/first available device print(f"Successfully connected to device: {d.info.get('serial', 'N/A')}") # Print basic device information print("Device Info:", d.info) # Get the current package and activity current_app = d.app_current() print(f"Current app: {current_app['package']} / {current_app['activity']}") # Take a screenshot and save it screenshot_path = "uiautomator2_quickstart_screenshot.png" d.screenshot(screenshot_path) print(f"Screenshot saved to {screenshot_path}") # Interact with the UI (example: press the Home button) d.press("home") print("Pressed Home button.") # Dump the current UI hierarchy (useful for inspecting elements) xml_dump = d.dump_hierarchy() print("UI Hierarchy (first 200 characters):", xml_dump[:200]) except Exception as e: print(f"An error occurred: {e}") print("\nTroubleshooting steps:") print("1. Ensure your Android device is connected via USB/WiFi and ADB debugging is enabled.") print("2. Run 'adb devices' in your terminal to confirm ADB detects your device.") print("3. Run 'python -m uiautomator2 init' (or 'u2 init') to install the uiautomator2 server on the device.") print("4. If connecting via IP, ensure the device is on the same network and you're using the correct IP.")
uiautomator2 --version
Debug
Known issues
gotchaThe `uiautomator2` server (atx-agent) must be installed and running on the Android device for the Python client to connect. Forgetting to initialize often leads to connection errors.
fix
Run `python -m uiautomator2 init` (or `u2 init` if installed as a command-line tool) from your terminal. This command installs the necessary APKs and starts the server on the connected device.
affects: All versions
breakinguiautomator2 has a tight dependency on specific versions of `adbutils`. Upgrading `adbutils` independently of `uiautomator2` might lead to compatibility issues or unexpected behavior, as breaking changes in `adbutils` are often addressed in subsequent `uiautomator2` releases.
fix
Always install/upgrade `uiautomator2` using `pip install uiautomator2 --upgrade`. This ensures compatible `adbutils` versions are installed. If issues arise, try reinstalling `uiautomator2` from scratch or checking its GitHub releases for specific `adbutils` compatibility notes.
affects: 3.x
gotchaAs of version 3.5.0, `d.send_keys()` automatically hides the input method after text entry. If your script previously included an explicit `d.hide_keyboard()` call immediately after `send_keys`, this might result in an unnecessary or problematic extra action.
fix
Review scripts using `d.send_keys()` and remove any redundant `d.hide_keyboard()` calls that follow directly. Test carefully, as behavior can vary slightly across Android versions.
affects: >=3.5.0
gotchaElement locators (e.g., XPath, text, resourceId) can be brittle. XPath is often slow and prone to breaking with minor UI changes. Text-based selectors can fail with localization or dynamic content. `resourceId` is generally the most stable if available and unique.
fix
Prioritize `resourceId` for element identification. If `resourceId` is not stable or unique, consider using a combination of attributes or relative positioning. Avoid complex or deeply nested XPath expressions for better performance and maintainability.
affects: All versions
Errors
Common errors & fixes
uiautomator2.exceptions.GatewayError: uiautomator2 server not started
The `atx-agent` server, which enables communication between the Python client and the Android device, is not running on the device.
fix
Run `python -m uiautomator2 init` (or `u2 init`) in your terminal. Ensure your device is connected via ADB and has granted debugging permissions. This command will install and start the necessary server.
AdbError: device not found
The Android Debug Bridge (ADB) cannot detect your device. This could be due to a disconnected cable, unauthorized device, missing ADB drivers, or an incorrect IP address/serial for wireless connection.
fix
1. Ensure the device is physically connected (if using USB). 2. Verify 'USB debugging' is enabled in Developer Options. 3. Check for 'Allow USB debugging?' prompt on the device and accept it. 4. Run `adb devices` in your terminal to confirm the device is listed. 5. If connecting wirelessly, ensure the IP address is correct and ADB is connected (`adb connect <ip>`).
No module named 'uiautomator2'
The `uiautomator2` Python package is not installed in your current Python environment.
fix
Install the package using pip: `pip install uiautomator2`.
AttributeError: 'UiObject' object has no attribute 'scroll_to_end'
Methods like `scroll_to_end` or `fling_to_end` are typically available only on UiObjects that are recognized as scrollable containers. Calling them on a generic or non-scrollable UiObject will raise an error.
fix
Ensure the `UiObject` you're targeting is indeed a scrollable element (e.g., a RecyclerView or ScrollView). If not, you might need to find its parent scrollable container or use general device-level scrolling methods like `d.scroll()` or `d.swipe()`.
Upgrade
Version history
3.5.2latest on PyPI · released May 28, 2026
Audit
Dependencies
adbutilsrequiredProvides underlying ADB communication; tight version coupling.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
uiautomator2 — pip install uiautomator2 · libregistry