Install & Compatibility
Where this runs
tested against v0.3.0.dev0 · 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
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.044s · 19.6MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 2.5s · import 0.041s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AdbClient
✓ from ppadb.client import Client as AdbClient
Device
✓ from ppadb.device.device import Device
Often obtained implicitly from AdbClient.devices() rather than instantiated directly.
This quickstart connects to the ADB server, lists connected devices, and performs basic operations like executing shell commands, pushing, and pulling files. Ensure an ADB server is running and a device is connected and authorized for it to work correctly.
from ppadb.client import Client as AdbClient
import os
# Ensure ADB server is running on 127.0.0.1:5037
# (e.g., run 'adb start-server' in your terminal)
host = os.environ.get('ADB_HOST', '127.0.0.1')
port = int(os.environ.get('ADB_PORT', 5037))
try:
# Connect to the ADB server
client = AdbClient(host=host, port=port)
# List connected devices
devices = client.devices()
if devices:
device = devices[0]
print(f"Connected to device: {device.serial}")
# Execute a shell command
result = device.shell("echo Hello from Android")
print(f"Shell command output: {result.strip()}")
# Example: Push a file (create a dummy file first)
with open('test_file.txt', 'w') as f:
f.write('This is a test file.\n')
device.push('test_file.txt', '/sdcard/test_file.txt')
print("Pushed test_file.txt to /sdcard/")
# Example: Pull a file
device.pull('/sdcard/test_file.txt', 'downloaded_test_file.txt')
print("Pulled test_file.txt to downloaded_test_file.txt")
os.remove('test_file.txt')
os.remove('downloaded_test_file.txt')
else:
print("No ADB devices found. Make sure a device is connected and authorized.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure the ADB server is running (e.g., 'adb start-server') and accessible.")
Debug
Known issues
gotchaThe ADB server must be running and accessible for `pure-python-adb` to connect. This library connects to an existing ADB server, it does not start one itself.fixBefore running your Python script, start the ADB server using the official Android SDK's `adb` command: `adb start-server`. Ensure no firewalls block port 5037 (the default).
affects: All
gotchaWhen connecting to an Android device for the first time, you will typically need to authorize the computer's ADB key on the device's screen.fixAfter connecting your device and starting the ADB server, look for a 'USB debugging connected' or 'Allow USB debugging?' prompt on your Android device and grant permission.
affects: All
gotchaThe `client.devices()` method will return an empty list if no devices are connected, authorized, or visible to the ADB server.fixVerify devices are connected and authorized by running `adb devices` in your terminal. Ensure USB debugging is enabled on your device.
affects: All
breakingThe library is currently at a `0.3.0.dev0` development version. APIs and internal behaviors are subject to change without strict backward compatibility guarantees.fixBe prepared for potential API adjustments in future releases. It's recommended to pin your dependency to the exact version you are using (`pure-python-adb==0.3.0.dev0`) if stability is critical, or monitor the GitHub repository for updates.
affects: 0.3.0.dev0 and earlier development releases
Errors
Common errors & fixes
ppadb.client.AdbError: failed to connect to '127.0.0.1:5037': Connection refused
The `pure-python-adb` client could not establish a connection to the ADB server. This typically means the ADB server is not running or is not accessible at the specified host and port.
fixFirst, ensure the official Android SDK's `adb` server is running by opening a terminal and executing `adb start-server`. Verify no firewalls are blocking port 5037. If the server is on a different host/port, initialize `AdbClient` with the correct `host` and `port` arguments.
IndexError: list index out of range
When attempting to access `devices[0]`, the `client.devices()` method returned an empty list, indicating no ADB devices were found or connected.
fixCheck if your Android device is properly connected via USB, has USB debugging enabled, and has authorized your computer's ADB key. Run `adb devices` in your terminal to confirm that your device is listed and not 'unauthorized'.
ModuleNotFoundError: No module named 'ppadb'
The `pure-python-adb` library has not been installed in the Python environment you are currently using, or there is a typo in the import statement.
fixInstall the library using pip: `pip install pure-python-adb`. Ensure your script is being executed in the same Python environment where the library was installed.
ppadb.client.AdbError: device unauthorized. Please check the confirmation dialog on your device.
The Android device requires authorization for the ADB connection. This happens on first connection or after revoking USB debugging authorizations.
fixLook at your Android device's screen. A dialog prompting 'Allow USB debugging?' should appear. Tap 'Allow' to authorize the connection. If no dialog appears, revoke USB debugging authorizations in Developer Options and re-connect.
Upgrade
Version history
0.3.0.dev0latest on PyPI · released Aug 5, 2020
Audit
Dependencies
rsaoptionalRequired for PythonRSAAuthSigner, an optional authentication method.
pycryptodomeoptionalRequired for PythonCryptodomeAuthSigner, an optional authentication method.