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 PATH
aapt2 or aapt (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

2.2 KiB Raw Blame History