adb-sideload-free-apps
Install free Android apps via ADB from F-Droid, GitHub Releases, GitLab Releases, Codeberg Releases, or generic HTTPS pages.
Requirements
- Python 3.11+
adb(Android Debug Bridge) in PATHaapt2oraapt(Android SDK Build Tools) in PATH
Quick start
python -m pip install -e .
cp config.example.toml config.toml
# Edit config.toml to add your apps
python -m sideload
Usage
sideload [APP] [--list] [--device SERIAL] [--dry-run] [--config PATH]
APP— app name from config (omit for interactive selection)--list— list configured apps--device,-s— ADB device serial--dry-run— resolve, download, validate without installing--config,-c— path to config.toml (default: ./config.toml)
Configuration
See config.example.toml. Supported sources:
| Source | Required fields |
|---|---|
fdroid |
url (page F-Droid) |
github |
url (repository) |
gitlab |
url (projet) |
codeberg |
url (repository Codeberg) |
generic |
url, asset_pattern (HTTPS page or directory) |
Every application also requires name and package. For GitHub, GitLab, and Codeberg,
set asset_pattern when a release contains more than one suitable APK. Debug,
test and unsigned APKs are rejected by default.
The generic source follows HTTPS anchor links from url. Use ordered
intermediate_patterns to navigate directories; when several links match, a
pattern with numeric capture groups selects the greatest numeric tuple.
asset_pattern is required and must match exactly one final APK. Optional
headers and sha256 are supported; header values are never logged.
aapt2 is used to validate the APK package ID before installation, with
aapt as a fallback for older Android SDK Build Tools. At least one of them
must be available in PATH. The script refuses to install an APK when neither
tool can validate it.
For Wi-Fi ADB, configure an explicit address after enabling wireless debugging:
[adb]
mode = "wifi"
address = "192.168.1.42:5555"
Testing
pip install pytest
python -m pytest tests/ -v