Android Debloater (ADB)

Debloat Android phones and Android TV devices through a single Bash script and ADB.

The script is intentionally conservative by default: it primarily disables packages instead of uninstalling them, which is safer to recover and typically safer for OTA updates.

📑 Table of Contents

• Capabilities
• Use Cases
• Usage
  • Basic Run
  • Recovery Commands
• Known Limitations
• System Requirements
• Installation
  • Manual Installation
  • Verification
• Privacy and Data
• Development
  • Requirements
  • Setup
  • Run
  • Linting
  • Continuous Integration
• GitHub Actions
• Project Structure
  • Directories
• Architecture
• Security
• Contributing
• Code of Conduct
• Project Engagement
• License

✨ Capabilities

• Detects connected Android devices through ADB and exits early when none are available.
• Distinguishes device type (Phone versus TV) through package heuristics.
• Installs alternative applications on phones when they are absent (Aurora Store, F-Droid, selected Fossify apps, Breezy Weather).
• Disables a substantial multi-vendor package set (Google, Samsung, Xiaomi, Asus, Oppo/OnePlus, and others).
• Uninstalls only a small, explicit subset of packages.

🎯 Use Cases

• Phone debloating: Remove or disable pre-installed bloatware on Android phones while provisioning privacy-respecting alternatives.
• TV debloating: Disable unwanted packages on Android TV devices without installing additional applications.

🚀 Usage

Basic Run

chmod +x android-debloater.sh
./android-debloater.sh

Recovery Commands

Re-enable a package:

adb shell pm enable --user 0 <package.name>

Reinstall an uninstalled system package (when still present in the system image):

adb shell pm install-existing --user 0 <package.name>

List disabled packages:

adb shell pm list packages --user 0 -d

⚠️ Known Limitations

• The script is non-interactive and executes immediately.
• Some package groups include core applications (dialer, contacts, messaging, camera, file manager), which can alter expected device conduct.
• Certain entries are uninstalled (not only disabled).
• Package availability differs by OEM, ROM, and Android version.
• APK download links in the provisioning section can become stale over time.

🖥️ System Requirements

Component	Minimum	Recommended
OS	Linux, macOS, or compatible shell environment with ADB	Linux
Runtime tools	adb, wget, bash	Latest stable versions
Device state	USB debugging enabled and ADB authorisation accepted	Authorised ADB connection

📦 Installation

This project is distributed as a single Bash script. No package manager installation is available.

Manual Installation

1. Download the latest android-debloater.sh from the releases page.
2. Make it executable:

   chmod +x android-debloater.sh

3. Ensure system requirements are met (see System Requirements).

Verification

./android-debloater.sh --help

(Note: The script currently does not implement a --help flag; running it without a connected device will exit with an error message.)

🛡️ Privacy and Data

Android Debloater collects no personal data and transmits nothing to the project maintainers. The only external network activity is optional HTTPS downloads of APK files from verified upstream sources (Aurora Store, F-Droid, Fossify, Breezy Weather) when provisioning alternative applications on phones.

For the detailed description of how the application handles privacy and personal data, see the Privacy Statement.

🛠️ Development

Requirements

• Bash
• Android Platform Tools (adb)
• ShellCheck
• wget

Setup

Debian/Ubuntu:

sudo apt update
sudo apt install -y android-tools-adb wget shellcheck

Arch Linux:

sudo pacman -Syy
sudo pacman -S android-tools wget shellcheck

Validate the ADB connection:

adb devices

Run

bash ./android-debloater.sh

Linting

shopt -s globstar nullglob
shellcheck **/*.sh --severity error

Continuous Integration

GitHub Actions validates every push and pull request targeting master. Reproduce the validation locally with:

shopt -s globstar nullglob
shellcheck **/*.sh --severity error

⚙️ GitHub Actions

Workflow	Purpose	What it does
bash.yml	ShellCheck validation	Checks out the repository and runs ShellCheck on all .sh files with error severity on every push and pull request to master.

🗂️ Project Structure

Directories

Directory	Purpose
docs/	Supplementary documentation covering architecture, configuration, testing, and other topics.
.github/workflows/	GitHub Actions workflow definitions.

🏗️ Architecture

Android Debloater automates a curated Android debloating procedure through one Bash entry point, android-debloater.sh. The script detects an attached device through ADB, classifies it as a phone or TV through an installed-package heuristic, optionally provisions alternative applications for phones, and then executes a long sequential package deactivation pass with a smaller explicit uninstall subset.

See the Architecture Documentation for the system context, principal components, runtime flows, ownership boundaries, dependencies, constraints, and extension points.

🔒 Security

See the security policy for supported versions, vulnerability reporting, scope, disclosure policy, and recognition.

🤝 Contributing

You are welcome to bring any suggestion, feedback or modification to this project.

When doing so, please:

• Maintain cross-platform compatibility
• Maintain the pull requests as focused and consistent with the existing code style
• Maintain your branch up-to-date with master
• Revise the documentation when behaviour changes
• Properly test all changes

📜 Code of Conduct

See the Code of Conduct for the standards of conduct expected in all project spaces.

💝 Project Engagement

Discovered a problem or have a suggestion? Open an issue!

If you find this project useful, consider funding it or starring ⭐️ it on GitHub!

📄 License

This project is being distributed under the GNU General Public License v3.0 or later. See LICENSE for details.