adb-sideload-free-apps

Install free Android apps via ADB from F-Droid, GitHub Releases, GitLab Releases, or Codeberg Releases.

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)

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.

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

1.7 KiB Raw Blame History