{"id":10068,"library":"pure-python-adb","title":"Pure Python ADB Client","description":"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.","status":"active","version":"0.3.0.dev0","language":"en","source_language":"en","source_url":"https://github.com/Swind/pure-python-adb","tags":["adb","android","debugging","mobile"],"install":[{"cmd":"pip install pure-python-adb","lang":"bash","label":"Install core library"},{"cmd":"pip install pure-python-adb[rsa]","lang":"bash","label":"Install with RSA for authentication"},{"cmd":"pip install pure-python-adb[cryptodome]","lang":"bash","label":"Install with PyCryptodome for authentication"}],"dependencies":[{"reason":"Required for PythonRSAAuthSigner, an optional authentication method.","package":"rsa","optional":true},{"reason":"Required for PythonCryptodomeAuthSigner, an optional authentication method.","package":"pycryptodome","optional":true}],"imports":[{"symbol":"AdbClient","correct":"from ppadb.client import Client as AdbClient"},{"note":"Often obtained implicitly from AdbClient.devices() rather than instantiated directly.","symbol":"Device","correct":"from ppadb.device.device import Device"}],"quickstart":{"code":"from ppadb.client import Client as AdbClient\nimport os\n\n# Ensure ADB server is running on 127.0.0.1:5037\n# (e.g., run 'adb start-server' in your terminal)\n\nhost = os.environ.get('ADB_HOST', '127.0.0.1')\nport = int(os.environ.get('ADB_PORT', 5037))\n\ntry:\n    # Connect to the ADB server\n    client = AdbClient(host=host, port=port)\n\n    # List connected devices\n    devices = client.devices()\n\n    if devices:\n        device = devices[0]\n        print(f\"Connected to device: {device.serial}\")\n\n        # Execute a shell command\n        result = device.shell(\"echo Hello from Android\")\n        print(f\"Shell command output: {result.strip()}\")\n\n        # Example: Push a file (create a dummy file first)\n        with open('test_file.txt', 'w') as f:\n            f.write('This is a test file.\\n')\n        device.push('test_file.txt', '/sdcard/test_file.txt')\n        print(\"Pushed test_file.txt to /sdcard/\")\n\n        # Example: Pull a file\n        device.pull('/sdcard/test_file.txt', 'downloaded_test_file.txt')\n        print(\"Pulled test_file.txt to downloaded_test_file.txt\")\n\n        os.remove('test_file.txt')\n        os.remove('downloaded_test_file.txt')\n\n    else:\n        print(\"No ADB devices found. Make sure a device is connected and authorized.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure the ADB server is running (e.g., 'adb start-server') and accessible.\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify devices are connected and authorized by running `adb devices` in your terminal. Ensure USB debugging is enabled on your device.","message":"The `client.devices()` method will return an empty list if no devices are connected, authorized, or visible to the ADB server.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.3.0.dev0 and earlier development releases"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ppadb.client.AdbError: failed to connect to '127.0.0.1:5037': Connection refused"},{"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'.","cause":"When attempting to access `devices[0]`, the `client.devices()` method returned an empty list, indicating no ADB devices were found or connected.","error":"IndexError: list index out of range"},{"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.","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.","error":"ModuleNotFoundError: No module named 'ppadb'"},{"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.","cause":"The Android device requires authorization for the ADB connection. This happens on first connection or after revoking USB debugging authorizations.","error":"ppadb.client.AdbError: device unauthorized. Please check the confirmation dialog on your device."}]}