{"id":6493,"library":"adbutils","title":"Adbutils","description":"Adbutils is a pure Python library for interacting with Android devices via the Android Debug Bridge (ADB) protocol. It provides a programmatic interface to control devices, install apps, execute shell commands, manage files, and more, without needing to directly invoke the `adb` command-line tool. The current version is 2.12.0, and it is actively maintained with frequent releases.","status":"active","version":"2.12.0","language":"en","source_language":"en","source_url":"https://github.com/openatx/adbutils","tags":["adb","android","device-control","automation","testing"],"install":[{"cmd":"pip install adbutils","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for some APK-related functionalities, particularly parsing and installing APK files.","package":"apkutils","optional":true}],"imports":[{"note":"The primary entry point is typically the `adb` object within the `adbutils` module.","symbol":"adbutils","correct":"import adbutils"}],"quickstart":{"code":"import adbutils\n\n# Get a list of connected devices\ndevices = adbutils.adb.devices()\nif devices:\n    print(f\"Connected devices: {len(devices)}\")\n    for i, d in enumerate(devices):\n        print(f\"  Device {i}: {d.serial} (status: {d.status})\")\n        # Example: Get a device object by serial or index\n        if i == 0:\n            device = d\n            print(f\"  First device model: {device.getprop('ro.product.model')}\")\n            # Example: Execute a shell command\n            output = device.shell(\"echo Hello from device\").strip()\n            print(f\"  Shell output: {output}\")\n            # Example: Push a file (requires a dummy file)\n            try:\n                with open('test.txt', 'w') as f:\n                    f.write('This is a test file.')\n                device.sync.push('test.txt', '/sdcard/test.txt')\n                print('  Pushed test.txt to /sdcard/test.txt')\n                device.shell('rm /sdcard/test.txt') # Clean up\n                print('  Cleaned up /sdcard/test.txt')\n            except Exception as e:\n                print(f\"  Could not push/cleanup test.txt (ignored for quickstart): {e}\")\nelse:\n    print(\"No ADB devices found. Make sure ADB server is running and devices are connected.\")\n\n# Ensure the ADB server is running\nif not adbutils.adb.server_version():\n    print(\"ADB server not running. Starting it...\")\n    adbutils.adb.start_server()\n    print(\"ADB server started.\")\nelse:\n    print(\"ADB server is already running.\")\n","lang":"python","description":"This quickstart code demonstrates how to list connected ADB devices, retrieve device properties, execute shell commands, and push a file to a device. It also includes logic to ensure the ADB server is running. Requires at least one ADB-enabled Android device connected and properly configured."},"warnings":[{"fix":"Ensure `adbutils` is updated to the latest version (>=2.9.2 provides better compatibility with `adb 1.0.39` and newer). If issues persist, try updating your system's Android SDK Platform Tools or checking the `adbutils` GitHub issues for specific version recommendations.","message":"Adbutils relies on the `adb` server (from Android SDK Platform Tools). Incompatibilities can arise between `adbutils` and specific `adb` server versions, leading to unexpected errors or connection issues.","severity":"gotcha","affected_versions":"< 2.9.2"},{"fix":"Upgrade to `adbutils` version 2.9.4 or higher to benefit from fixes addressing socket and connection leaks.","message":"Older versions of `adbutils` might suffer from connection or socket leaks, especially when using `shell v2` or `create_connection`, leading to resource exhaustion over time.","severity":"gotcha","affected_versions":"< 2.9.4"},{"fix":"Upgrade `adbutils` to version 2.11.0 or newer to ensure proper functionality with `apkutils 2.0.1` and later versions for APK installation features.","message":"When installing APKs using `device.install()`, ensure compatibility with the `apkutils` library. Specifically, `adbutils` versions prior to 2.11.0 had compatibility issues with `apkutils 2.0.1`.","severity":"gotcha","affected_versions":"< 2.11.0"},{"fix":"Update `adbutils` to version 2.11.0 or newer to resolve known Windows `PermissionError` issues during APK downloads.","message":"On Windows, older versions of `adbutils` could encounter `PermissionError` when attempting to download APKs.","severity":"gotcha","affected_versions":"< 2.11.0"},{"fix":"Upgrade `adbutils` to version 2.11.0 or newer to fix the `send_keys` behavior when the input contains a dot.","message":"The `device.send_keys()` method had a bug where it would not correctly process input strings containing a dot ('.').","severity":"gotcha","affected_versions":"< 2.11.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Ensure 'adbutils' is installed by running 'pip install adbutils' and verify it's in the correct Python environment.","cause":"The 'adbutils' module is not installed or not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'adbutils'"},{"fix":"Downgrade 'apkutils' to a compatible version by running 'pip install apkutils==1.0.0'.","cause":"The 'apkutils' library version is incompatible, missing the 'get_main_activities' method.","error":"AttributeError: 'APK' object has no attribute 'get_main_activities'"},{"fix":"Verify the source and destination paths, ensure the device has sufficient storage and permissions for the operation, and check the ADB logs for more detailed error messages. Sometimes, restarting the ADB server (`adb kill-server` then `adb start-server`) or the device can resolve transient issues.","cause":"This is a generic ADB command failure, often encountered during file transfer operations like `device.sync.push()`, indicating that the underlying ADB server reported a failure without a more specific error code.","error":"adbutils.errors.AdbError: FAIL"},{"fix":"Specify the `serial` number of the target device when calling `adb.device()`, for example: `d = adb.device(serial='YOUR_DEVICE_SERIAL_NUMBER')`. You can get a list of connected devices and their serials using `adb.device_list()`.","cause":"When multiple Android devices or emulators are connected, calling `adbutils.adb.device()` without specifying a `serial` argument is ambiguous, and `adbutils` raises this error to prevent an arbitrary device from being selected.","error":"RuntimeError: Multiple devices connected, but no serial specified"}]}