How UAD-NG Debloat Lists (`uad_lists.json`) Are Structured and Used for Package Recommendations

The debloat lists in Universal Android Debloater-Next Generation (UAD-NG) are JSON files embedded at compile time that map Android package names to metadata including removal safety levels, which the CLI and GUI filter to generate package recommendations.

The Universal Android Debloater-Next Generation (UAD-NG) relies on a centralized JSON database to determine which Android packages are safe to remove. Understanding the debloat lists (uad_lists.json) structure is essential for contributors and advanced users who want to customize recommendations or understand how the safety classification system works. This file drives the entire recommendation engine for both the command-line interface and the graphical user interface.

JSON Structure and Metadata Fields

The canonical debloat list resides at resources/assets/uad_lists.json in the repository root. This file contains a single JSON object where each key represents a fully-qualified Android package identifier.

Package Identifier Keys

Top-level keys use standard Android package naming conventions (e.g., com.android.bluetooth). Each key maps to an object containing metadata fields that drive the recommendation engine.

Core Metadata Fields

Every package entry contains the following fields:

• list – Categorizes the source origin (Aosp, Oem, Carrier, Google, Misc, Pending, or Unlisted)
• description – Human-readable explanation of the package's purpose
• dependencies – Array of package names that must remain installed for this package to function
• neededBy – Array of packages that depend on this one
• labels – Optional tags for UI grouping and filtering

The Removal Recommendation Field

The removal field is the critical component for package recommendations. It accepts one of five values:

• Recommended – Safe to remove for most users
• Advanced – Removal requires some technical knowledge
• Expert – Only for expert users who understand potential breakage
• Unsafe – Likely to break core functionality
• Unlisted – Not yet categorized

Rust Data Models and Deserialization

The UAD-NG codebase defines Rust structs that mirror the JSON schema exactly, enabling type-safe deserialization via Serde.

The Package Struct

Defined in crates/uad-core/src/uad_lists.rs (lines 21-30), the Package struct captures every JSON field:

pub struct Package {
    pub list: UadList,
    pub description: String,
    pub dependencies: Vec<String>,
    pub needed_by: Vec<String>,
    pub labels: Vec<String>,
    pub removal: Removal,
}

The type alias PackageHashMap represents the deserialized data as HashMap<String, Package>.

UadList and Removal Enums

Lines 32-42 define the UadList enum for source categorization, while lines 54-62 define the Removal enum for safety levels. These enums ensure that only valid values from the JSON are accepted at runtime.

Loading and Runtime Usage

UAD-NG embeds the debloat list directly into the binary to ensure offline functionality, then deserializes it at runtime.

Embedding with include_str

At line 19 of crates/uad-core/src/uad_lists.rs, the JSON is embedded using the include_str! macro:

const UAD_LISTS_JSON: &str = include_str!("../../../resources/assets/uad_lists.json");

This guarantees the tool ships with a complete, offline-capable database.

The load_debloat_lists Function

The load_debloat_lists function (lines 207-215) handles deserialization and optional remote updates:

pub fn load_debloat_lists(remote: bool) -> Result<PackageHashMap, PackageHashMap> {
    // If remote is true, attempts to fetch latest from GitHub
    // Otherwise, or on failure, deserializes UAD_LISTS_JSON
    serde_json::from_str(UAD_LISTS_JSON)
        .map_err(|_| /* fallback logic */)
}

When remote is false, the function parses the embedded string. When true, it attempts to download the latest version from GitHub, falling back to the embedded copy on network failure.

Filtering for Package Recommendations

Both the CLI and GUI consume the PackageHashMap to present filtered views based on user-selected safety levels.

CLI Filtering by Removal Level

The CLI implements RemovalFilter in crates/uad-cli/src/filters.rs to match packages against desired safety levels:

pub enum RemovalFilter {
    Recommended,
    Advanced,
    Expert,
    Unsafe,
    Unlisted,
}

impl RemovalFilter {
    pub fn matches(&self, info: &PackageInfo) -> bool {
        match self {
            Self::Recommended => info.removal == Removal::Recommended,
            Self::Advanced    => info.removal == Removal::Advanced,
            Self::Expert      => info.removal == Removal::Expert,
            Self::Unsafe      => info.removal == Removal::Unsafe,
            Self::Unlisted    => info.removal == Removal::Unlisted,
        }
    }
}

This allows users to run commands like --filter Recommended to see only safe removals.

GUI Filtering and Expert Mode

In the GUI layer (crates/uad-gui/src/views/list.rs and crates/uad-gui/src/widgets/package_row.rs), the removal field drives the visual presentation. The application checks the expert_mode setting before displaying Unsafe packages:

// Inside package_row.rs
if self.removal != Removal::Unsafe || settings.general.expert_mode {
    // Render normally
} else {
    // Show warning badge or disable row
}

This protects casual users from accidentally removing critical system components while allowing experts to access all options.

Summary

• The debloat lists (uad_lists.json) use a JSON object structure with package IDs as keys and metadata objects as values.
• The removal field categorizes packages into Recommended, Advanced, Expert, Unsafe, or Unlisted safety levels.
• The file is embedded at compile time via include_str! in crates/uad-core/src/uad_lists.rs and deserialized into a PackageHashMap.
• The load_debloat_lists function supports both offline (embedded) and online (remote) loading with automatic fallback.
• CLI filters use RemovalFilter to match packages by safety level, while the GUI respects expert mode settings when displaying Unsafe entries.

Frequently Asked Questions

What happens if uad_lists.json is corrupted or missing?

UAD-NG embeds a default copy of uad_lists.json directly into the binary using include_str! at line 19 of crates/uad-core/src/uad_lists.rs. If the remote fetch fails or the local file is corrupted, the application falls back to this embedded version, ensuring the tool never crashes due to missing list data.

How does UAD-NG determine the removal recommendation for a package?

The removal field in uad_lists.json is manually curated by the Universal Debloater Alliance community based on testing and user reports. Each package is classified as Recommended, Advanced, Expert, or Unsafe depending on the likelihood and severity of system breakage when removed, with Unlisted indicating packages awaiting review.

Can I customize the debloat lists for my specific device?

Yes. While UAD-NG ships with the standard uad_lists.json, you can modify the JSON file in the resources/assets/ directory before compiling, or contribute device-specific entries to the upstream repository. The structure supports custom labels and dependencies to handle OEM-specific variations, and the load_debloat_lists function will parse your custom entries into the same PackageHashMap structure.

Why does the GUI hide some packages that appear in the CLI?

The GUI respects an "expert mode" setting that filters out Removal::Unsafe entries by default to prevent accidental system damage. In crates/uad-gui/src/widgets/package_row.rs, the application checks this setting before rendering packages. Enable expert mode in the GUI settings to view all packages including those marked Unsafe.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}