Registry / devops / adbutils

adbutils

JSON →
library2.12.0pypypi✓ verified 84d ago

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.

pip install adbutils
INSTALL
IMPORT
SIG · ADBUTILS
A
adbutils
devopspythonv2.12.0
Install
3.1s avg
Import
680ms
Disk
45MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.12.0 · 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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.708s · 43.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.1s · import 0.651s · 51MB
45MB installed
● package 45MB
Code
Verified usage

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

adbutils
import adbutils
The primary entry point is typically the `adb` object within the `adbutils` module.

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.

import adbutils # Get a list of connected devices devices = adbutils.adb.devices() if devices: print(f"Connected devices: {len(devices)}") for i, d in enumerate(devices): print(f" Device {i}: {d.serial} (status: {d.status})") # Example: Get a device object by serial or index if i == 0: device = d print(f" First device model: {device.getprop('ro.product.model')}") # Example: Execute a shell command output = device.shell("echo Hello from device").strip() print(f" Shell output: {output}") # Example: Push a file (requires a dummy file) try: with open('test.txt', 'w') as f: f.write('This is a test file.') device.sync.push('test.txt', '/sdcard/test.txt') print(' Pushed test.txt to /sdcard/test.txt') device.shell('rm /sdcard/test.txt') # Clean up print(' Cleaned up /sdcard/test.txt') except Exception as e: print(f" Could not push/cleanup test.txt (ignored for quickstart): {e}") else: print("No ADB devices found. Make sure ADB server is running and devices are connected.") # Ensure the ADB server is running if not adbutils.adb.server_version(): print("ADB server not running. Starting it...") adbutils.adb.start_server() print("ADB server started.") else: print("ADB server is already running.")
Debug
Known issues
gotchaAdbutils 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.
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.
affects: < 2.9.2
gotchaOlder versions of `adbutils` might suffer from connection or socket leaks, especially when using `shell v2` or `create_connection`, leading to resource exhaustion over time.
fix
Upgrade to `adbutils` version 2.9.4 or higher to benefit from fixes addressing socket and connection leaks.
affects: < 2.9.4
gotchaWhen 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`.
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.
affects: < 2.11.0
gotchaOn Windows, older versions of `adbutils` could encounter `PermissionError` when attempting to download APKs.
fix
Update `adbutils` to version 2.11.0 or newer to resolve known Windows `PermissionError` issues during APK downloads.
affects: < 2.11.0
gotchaThe `device.send_keys()` method had a bug where it would not correctly process input strings containing a dot ('.').
fix
Upgrade `adbutils` to version 2.11.0 or newer to fix the `send_keys` behavior when the input contains a dot.
affects: < 2.11.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'adbutils'
The 'adbutils' module is not installed or not accessible in the current Python environment.
fix
Ensure 'adbutils' is installed by running 'pip install adbutils' and verify it's in the correct Python environment.
AttributeError: 'APK' object has no attribute 'get_main_activities'
The 'apkutils' library version is incompatible, missing the 'get_main_activities' method.
fix
Downgrade 'apkutils' to a compatible version by running 'pip install apkutils==1.0.0'.
adbutils.errors.AdbError: FAIL
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.
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.
RuntimeError: Multiple devices connected, but no serial specified
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.
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()`.
Upgrade
Version history
2.12.0latest on PyPI · released Nov 12, 2025
Audit
Dependencies
apkutilsoptionalRequired for some APK-related functionalities, particularly parsing and installing APK files.
Agent activity
97 hits · last 30 days
node
84
OpenAI (training)
1
Resources
adbutils — pip install adbutils · libregistry