Pure Python ADB Client

0.3.0.dev0 · active · verified Fri Apr 17

pure-python-adb provides a pure Python implementation of the Android Debug Bridge (ADB) client protocol. It allows Python applications to interact with ADB servers and connected Android devices programmatically, enabling tasks like shell commands, file transfers, and application management. The current version is 0.3.0.dev0, indicating active development with potential for API changes. Release cadence is irregular, as typical for a development branch.

Common errors

```
ppadb.client.AdbError: failed to connect to '127.0.0.1:5037': Connection refused
```
cause 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.

fix First, 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
```
cause When attempting to access `devices[0]`, the `client.devices()` method returned an empty list, indicating no ADB devices were found or connected.

fix Check 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'
```
cause 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.

fix Install 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.
```
cause The Android device requires authorization for the ADB connection. This happens on first connection or after revoking USB debugging authorizations.

fix Look 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.

Warnings

gotcha The 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.
Fix: Before 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).
gotcha When 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.
Fix: After 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.
gotcha The `client.devices()` method will return an empty list if no devices are connected, authorized, or visible to the ADB server.
Fix: Verify devices are connected and authorized by running `adb devices` in your terminal. Ensure USB debugging is enabled on your device.
breaking The library is currently at a `0.3.0.dev0` development version. APIs and internal behaviors are subject to change without strict backward compatibility guarantees.
Fix: Be 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.

Install

pip install pure-python-adb Install core library
pip install pure-python-adb[rsa] Install with RSA for authentication
pip install pure-python-adb[cryptodome] Install with PyCryptodome for authentication

Imports

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.

Quickstart

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.")

view raw JSON →