Introduction

tools:overrideLibrary is not a build.gradle setting. It is an Android manifest attribute used during manifest merging to bypass a library's declared minSdkVersion restriction when you know the library is still safe to use on your app's lower minSdk.

What the Attribute Actually Does

When an Android library declares a higher minSdkVersion than your app, manifest merging can fail. tools:overrideLibrary tells the merge process:

"Allow this specific library package even though its manifest says it needs a higher minimum SDK."

That means the attribute belongs in AndroidManifest.xml, not in Gradle dependency declarations.

Correct Placement

The attribute is typically added to your app manifest's uses-sdk element:

1<manifest xmlns:android="http://schemas.android.com/apk/res/android"
2    xmlns:tools="http://schemas.android.com/tools">
3
4    <uses-sdk
5        tools:overrideLibrary="com.example.library" />
6
7</manifest>

If more than one library needs overriding, separate the package names with commas:

<uses-sdk
    tools:overrideLibrary="com.example.library,com.example.otherlibrary" />

The package names here are the manifest package names of the libraries being overridden.

When You Should Use It

Use tools:overrideLibrary only when:

• manifest merge fails because a library declares a higher minSdkVersion
• you have verified that the library code paths you use are still safe on your lower minSdk
• you are intentionally taking responsibility for compatibility

This is a targeted compatibility override, not a general dependency conflict tool.

What It Does Not Solve

It does not fix:

• Java or Kotlin version conflicts
• duplicate classes
• Gradle dependency version mismatches
• runtime API calls that actually require the higher SDK

That last point is the dangerous one. If the library really calls APIs unavailable on your app's minSdk, the app may compile and install but still crash at runtime on older devices.

Example Scenario

Suppose your app has:

defaultConfig {
    minSdk = 21
}

and a library manifest effectively demands minSdk 24. If you have tested and confirmed the part of the library you use works on API 21, you can add the manifest override.

Your build.gradle still contains the dependency normally:

dependencies {
    implementation("com.example:some-library:1.2.3")
}

But the override itself remains in the manifest:

<uses-sdk
    tools:overrideLibrary="com.example.somelibrary" />

That separation is important:

• Gradle declares dependencies
• the manifest controls the merge override

Why the Name Causes Confusion

Developers often search for a Gradle solution because the build error appears during the build, but the root issue is manifest metadata. The tools namespace belongs to Android manifest merging rules, so the fix naturally lives in XML rather than in the Gradle DSL.

That is why trying to put tools:overrideLibrary directly into build.gradle does nothing useful.

Safer Alternatives

Before overriding, prefer safer options when possible:

• upgrade your app's minSdkVersion
• choose a compatible library version
• remove the incompatible library feature
• guard high-API code paths with proper SDK checks

An override is a conscious compatibility gamble. It can be the right move, but only after verification.

Common Pitfalls

• Searching for a build.gradle syntax for tools:overrideLibrary even though it is a manifest attribute.
• Using the override to silence the merge error without testing the library on the lower SDK versions you still support.
• Assuming it resolves general dependency problems instead of the specific manifest minSdkVersion conflict.
• Writing the wrong package name in the override list, which leaves the merge issue unresolved.
• Treating the attribute as harmless boilerplate when it actually shifts compatibility responsibility to your app.

Summary

• 'tools:overrideLibrary belongs in AndroidManifest.xml, not in build.gradle.'
• It is used to bypass a library's manifest minSdkVersion requirement during manifest merging.
• Only use it when you have verified the library is still safe on your supported lower SDK versions.
• It does not solve general Gradle or dependency-version conflicts.
• Prefer compatible dependencies or a higher app minSdk when that is feasible.