How to Fix Unity Android Build Setup: SDK, NDK, JDK and Player Settings Explained

Getting a Unity project onto an Android device for the first time is one of those tasks that looks like it should take ten minutes and somehow takes three hours. Not because it is inherently complicated, but because the error messages are opaque, the settings are scattered across four different windows, and the documentation assumes you already know what an NDK is.

My first Android build attempt produced an error about a missing build-tools version. I had no idea what build-tools were or where they were supposed to live. The second attempt failed because I had the wrong NDK. The third worked, but only in the editor — plugging in my phone and running it directly took another half hour of USB debugging setup that no tutorial had mentioned.

This guide covers all of it: installing the right modules through Unity Hub, configuring the Player Settings that actually matter, understanding APK versus AAB, and fixing the errors that hit almost everyone during their first Android build.

What You Actually Need

To build for Android in Unity you need three things beyond the editor itself:

• Android SDK — the Software Development Kit. Contains the tools Unity uses to compile and package your game for Android.
• NDK — the Native Development Kit. Required for IL2CPP builds (which is what you want for release). Without it, IL2CPP compilation fails entirely.
• OpenJDK — a Java Development Kit. Android's build system (Gradle) needs Java. Unity bundles its own OpenJDK so you do not need to install Java separately.

The good news: you do not need to download any of these manually. Unity distributes all three as modules through Unity Hub, and installing them through Hub ensures you get the exact versions Unity supports for your editor version. Installing them from other sources and pointing Unity at them manually is something you can do, but it is a reliable way to create version mismatch errors that waste hours.

Part 1: Installing Android Support Through Unity Hub

If you did not check Android Build Support when you first installed Unity, you need to add it as a module.

1. Open Unity Hub.
2. Go to the Installs tab.
3. Find the Unity version you are using and click the gear icon next to it.
4. Select Add Modules.
5. Check Android Build Support.
6. Under it, also check Android SDK & NDK Tools and OpenJDK. These are sub-items that only appear when Android Build Support is expanded.
7. Click Install and wait. This downloads around 2-3GB depending on your Unity version.

The sub-items are easy to miss. The first time I did this I only checked the parent "Android Build Support" checkbox and skipped the children, which meant the SDK and NDK were never installed. Unity gave me a vague error about missing build tools rather than saying "hey, you forgot to install the NDK."

After installation, confirm it worked: open Unity, go to Edit > Preferences > External Tools, scroll to the Android section. You should see populated paths for the JDK, SDK, and NDK. If any of them say "Not installed" or show a warning icon, the module did not install correctly and you need to go back to Hub and try again.

Part 2: Switching Platform to Android

1. In Unity, go to File > Build Settings.
2. Select Android from the platform list.
3. Click Switch Platform.

This triggers a reimport of all your assets for the Android platform. On a large project it can take 5-20 minutes. On a small one, a minute or two. Unity needs to reimport because different platforms use different texture compression formats and asset configurations — what works on PC does not necessarily translate directly to Android.

After the switch completes, the Android icon appears next to your scene files in the Project window, confirming the active platform has changed.

Part 3: Player Settings That Actually Matter

This is where most beginners either skip too many things or get overwhelmed trying to understand everything at once. Here are the settings worth actually caring about for your first build.

Open them through Edit > Project Settings > Player, then click the Android icon tab at the top.

Company Name and Product Name

These appear in the app listing on the device and in the Play Store. Set them before your first build — changing them later does not automatically update existing installs.

Package Name

This is the unique identifier for your app across all Android devices and the Play Store. The format is reverse domain notation: com.yourcompany.gamename. Rules that matter:

• Lowercase only.
• No spaces or special characters except dots.
• Must be globally unique if you plan to publish to the Play Store.
• Once you publish an app with a specific package name, you cannot change it without it being treated as a completely different app.

For personal projects with no Play Store plans, something like com.yourlastname.projectname is fine. The default Unity value (com.DefaultCompany.ProjectName) will cause a rejection if you try to submit it.

Minimum API Level

Unity supports Android 6.0 "Marshmallow" (API level 23) and above. The minimum API level controls which Android versions can install your app. Setting it lower means more devices can install it; setting it higher locks out older devices but lets you use newer Android features.

For most games, API level 24 (Android 7.0) or 26 (Android 8.0) is a reasonable minimum in 2026. The exact choice depends on what percentage of your target audience you are willing to exclude. Google's Android distribution dashboard (accessible through the Play Console) shows current API level distribution if you want data on this.

Target API Level

The Unity Hub installs the latest version of the Android SDK Target API that Google Play requires. Google updates this requirement roughly annually. As of mid-2026, Google Play requires apps to target a minimum API level that they publish in their developer documentation — check developer.android.com/google/play/requirements/target-sdk for the current requirement before submitting, since this number goes up every year and an outdated target API level will cause a Play Store submission rejection.

For local testing on a device without Play Store submission, the default value Unity installs is fine.

Scripting Backend

Option	What It Is	When To Use It
Mono	Faster build times, easier debugging, larger final app size.	Development and testing builds where fast iteration matters more than performance.
IL2CPP	Converts C# to C++ before compilation. Slower builds, smaller and faster final app, required for 64-bit.	Release builds and any build going to the Play Store. Google Play requires 64-bit support, which means IL2CPP.

Use Mono during development. Switch to IL2CPP for your release build. The build time difference is significant — IL2CPP builds take considerably longer, which makes it painful as a daily development workflow. Many developers keep Mono as default and only switch when doing a release candidate build.

Target Architectures

Google Play requires applications to support 64-bit architecture. That means you need ARM64 checked. ARMv7 (32-bit) can also be checked for wider device compatibility, but ARM64 is non-negotiable for Play Store submissions.

Part 4: APK vs AAB — Which Should You Build

Format	What It Is	When To Use It
APK	Android Package. A single file containing everything needed to install the app. Can be installed directly on a device.	Local testing on a device, sharing builds with testers outside the Play Store, builds you want to install by transferring a file.
AAB	Android App Bundle. Google's modern format that lets Play Store generate device-specific APKs rather than shipping one giant APK to everyone.	Play Store submissions. Google has required AAB for new apps since August 2021.

For testing on your own device during development: build APK, copy it to your phone, install it. For submitting to the Play Store: build AAB. The Build Settings window has a checkbox for "Build App Bundle (Google Play)" — check it for Play Store builds, uncheck it for local test builds.

Part 5: Building and Running on a Physical Device

Building an APK and transferring it manually is the simplest path. Running directly to a connected device is faster once it is set up.

Enabling USB Debugging

1. On your Android phone, go to Settings > About Phone.
2. Tap Build Number seven times. This unlocks Developer Options.
3. Go back to Settings, find Developer Options, and enable both Developer Options and USB Debugging.
4. Connect the phone to your computer with a USB cable.
5. On the phone, accept the prompt asking if you trust this computer.

The seven-tap thing is one of those pieces of Android trivia that everyone forgets exists until they need it. The prompt that appears on the phone after connecting is easy to miss if the screen dims while you are still on the computer — unlock it and check for the dialog.

Running Directly to Device from Unity

1. In Build Settings, confirm your device appears in the Run Device dropdown. If it is not listed, the USB debugging setup did not complete or the driver is missing on Windows.
2. Click Build and Run. Unity builds the APK and deploys it to the connected device automatically.

On Windows, some Android devices require a specific USB driver that is not included with Windows by default. If your device does not appear in the dropdown after correctly enabling USB debugging, search for "[your phone manufacturer] ADB driver Windows" and install the driver from the manufacturer's site. Samsung, Google Pixel, and most major brands have drivers available directly from their support pages.

Part 6: Keystore Setup for Release Builds

Every app on the Play Store must be signed with a keystore — a digital certificate that identifies you as the app's author. For local testing, Unity can sign with a debug keystore automatically. For Play Store submission, you need your own.

Creating a Keystore

1. In Unity, go to Edit > Project Settings > Player > Publishing Settings.
2. Click Keystore Manager.
3. Click Keystore > Create New > Anywhere.
4. Choose a safe location to save the file and give it a name.
5. Set a strong password and confirm it.
6. Fill in the Key details (alias, password, validity in years, and your name or organization).
7. Click Add Key.

The keystore password and key password need to be remembered forever. If you lose them, you cannot update your app on the Play Store — Google will treat any new build signed with a different keystore as a completely separate app. Store them somewhere secure. Many developers keep them in a password manager alongside the keystore file backed up to a private cloud location.

Also: never commit the keystore file to a public Git repository. It is effectively a signing credential for your published app. Keep it in a private repo or out of version control entirely, and add it to your .gitignore.

Common Errors and How to Fix Them

Error: "Android SDK Build-Tools not found"

Cause: The Android SDK module was not installed through Unity Hub, or was installed but Unity is pointing at an external SDK installation that is missing required build tools.

Fix: Go to Edit > Preferences > External Tools > Android and check whether the SDK path points to Unity Hub's managed installation. If not, or if the path is empty, reinstall the Android Build Support module through Unity Hub and let Unity use its bundled SDK.

Error: "NDK not found" or "Unsupported NDK version"

Cause: The NDK sub-module was not installed alongside Android Build Support, or you switched Unity versions without reinstalling modules, or a custom NDK path is pointing to a version Unity does not support.

Fix: Unity only officially supports the NDK version it supplies through Unity Hub. Remove any custom NDK path from Preferences > External Tools and reinstall the Android SDK & NDK Tools module through Hub for your specific Unity version.

Error: "IL2CPP build failed" with no clear reason

Cause: Several possible causes — missing NDK for IL2CPP compilation, C++ compilation error in generated code, or a managed code stripping issue removing something that was needed.

Fix: First confirm the NDK is installed and detected. Then check the full build log (available in the Console window after expanding the error) for the actual C++ compiler error, which is usually more specific. If it mentions "type or namespace not found" in stripped code, add a link.xml file to the Assets folder to preserve the referenced types from stripping.

Error: "Package name already exists" on Play Store submission

Cause: Another app on the Play Store already uses your package name, or you are trying to submit as a new app but the package name was previously used by a different account.

Fix: Change the package name in Player Settings to something unique. Appending a word, year, or version suffix while the name is unclaimed is the common workaround.

Error: Device not appearing in Run Device dropdown

Cause: USB Debugging is not enabled on the device, the device is in a charging-only USB mode rather than file transfer mode, or a USB driver is missing on Windows.

Fix: Confirm USB Debugging is enabled in Developer Options. On the phone, change the USB connection mode to "File Transfer" or "MTP" rather than "Charging." On Windows, install the manufacturer's ADB driver if the device is still not detected.

Error: App installs but crashes immediately on device

Cause: Usually a scripting error that does not surface in the editor, a missing permission the app needs, or a texture format the device does not support.

Fix: Connect the device, open a terminal, and run adb logcat while the app crashes. The logcat output shows the actual exception or error. This is the most reliable way to diagnose device-specific crashes that produce no useful information from the Unity editor alone.

Texture Compression: ASTC Is What You Want

Unity's default texture compression format for Android is ASTC. It is the right choice for almost every project targeting modern Android hardware. If an Android device does not support the texture compression format you use, Unity decompresses the texture at runtime, which increases memory usage and decreases rendering speed.

ASTC support is universal on Android devices released after around 2016, so unless you are explicitly targeting very old hardware, leave texture compression at the default ASTC and do not overthink it.

If you need to support a wider range of very old devices, ETC2 is the safer but lower-quality fallback. In practice this is rare for new projects in 2026.

Beginner Mistakes

• Installing Android Build Support but missing the SDK/NDK sub-modules. The parent checkbox and the children are separate. Both need to be checked. Missing NDK specifically causes IL2CPP builds to fail with cryptic errors.
• Using Mono scripting backend for Play Store submissions. Mono does not support 64-bit ARM64, which Google Play requires. IL2CPP is mandatory for release builds.
• Leaving the default package name (com.DefaultCompany.ProjectName). This will be rejected by the Play Store and may conflict with other projects on your own device.
• Losing the keystore file or its password. Without both, you cannot update your published app. Back them up before you need them, not after.
• Committing the keystore to a public repository. Add it to .gitignore. A public keystore is a security problem for your published app.
• Building AAB for local device testing. AAB files cannot be sideloaded directly. Build APK for testing on a physical device, AAB for Play Store submissions.
• Testing only in the Unity editor and skipping real device testing before submission. The editor does not accurately reflect performance on actual Android hardware, and some bugs only surface on device.

Best Practices

• Install SDK, NDK, and OpenJDK through Unity Hub for your exact editor version. Never point Unity at an external Android Studio installation unless you have a specific reason.
• Use Mono scripting backend during development and switch to IL2CPP only for release builds to keep daily build times manageable.
• Set your package name before your first build — not as an afterthought after you realize you need it for the Play Store.
• Store the keystore file and both passwords in a password manager and back up the keystore file to a private location outside your main codebase.
• Add the keystore file path to .gitignore if it lives anywhere inside your project folder.
• Test on a real device early and often, not just in the editor. Performance, input feel, and resolution behavior all differ from the editor simulation.
• Use adb logcat for any crash that produces no useful information from Unity's console alone.

Frequently Asked Questions

What do I need to build for Android in Unity?

Android Build Support plus its Android SDK and NDK Tools and OpenJDK sub-modules, all installed through Unity Hub. You also need to switch the active platform to Android in Build Settings.

Should I install the Android SDK separately or use Unity's bundled version?

Use Unity Hub's bundled version. It installs exactly the SDK and NDK versions Unity supports for your editor version. External installations from Android Studio frequently cause version mismatch errors that are difficult to diagnose.

What is the difference between APK and AAB?

APK is a complete installable file you can transfer and install directly on a device. AAB is Google's modern format for Play Store submissions that lets Google generate device-optimized APKs rather than shipping one large file to everyone. Use APK for local testing, AAB for Play Store submissions.

What scripting backend should I use for Android?

Mono for development builds (faster iteration), IL2CPP for release builds. Google Play requires 64-bit ARM64 support, which needs IL2CPP. Mono builds are faster to compile and easier to debug, making them the practical default during daily development.

What is a keystore and do I need one?

A keystore is a digital certificate that identifies you as the publisher of your app. It is required for Play Store submissions. Unity uses a temporary debug keystore for local testing automatically. You only need to create your own keystore when preparing a release build for the Play Store.

What happens if I lose my keystore?

You cannot update your published app on the Play Store. Google treats a build signed with a different keystore as a completely separate app, so existing installs cannot receive updates from the new keystore. Back it up securely before you need it.

Why is my device not appearing in Unity's Run Device dropdown?

USB Debugging is most likely not enabled on the device, the USB connection is in charging mode rather than file transfer mode, or a USB driver is missing on Windows. Enable Developer Options by tapping Build Number seven times in Settings, then enable USB Debugging.

What is the minimum API level I should target?

API level 24 (Android 7.0) or 26 (Android 8.0) covers the vast majority of active Android devices in 2026. Lower values support more devices but may prevent using some modern Android features. Check Google's distribution dashboard for current market share data if you want to make a data-informed decision.

Does Google Play require 64-bit support?

Yes. Google Play requires ARM64 support, which means you must use the IL2CPP scripting backend and check ARM64 in Target Architectures in Player Settings.

Why did my app crash on device but not in the editor?

The editor does not perfectly replicate Android hardware behavior. Connect the device and run adb logcat in a terminal while reproducing the crash to see the actual error message, which is usually far more specific than anything Unity's console shows for device-side crashes.

What texture compression format should I use for Android?

ASTC is Unity's default and the right choice for virtually all projects targeting hardware from 2016 onward. If runtime decompression is happening on a specific device, the editor console and adb logcat both report it.

Can I test an Android build without a physical device?

Unity does not support Android emulators. You need a physical device. For quick layout testing at different screen sizes, the Game view's resolution dropdown in the editor is a reasonable substitute for basic UI work, but it does not reflect actual performance or touch input behavior.

Key Takeaways

• Install Android Build Support plus its SDK/NDK and OpenJDK sub-modules through Unity Hub, not from external sources.
• Use Mono for development builds and IL2CPP for release builds. ARM64 is required for Play Store submissions.
• Set your package name before your first build. Change it later and you are effectively creating a new app.
• Back up your keystore file and passwords securely before publishing. Losing them means losing the ability to update your app.
• Build APK for device testing, AAB for Play Store submissions.
• Use adb logcat for any crash that produces no useful information from the Unity console.

Action Steps

1. Open Unity Hub, go to Installs, and add Android Build Support plus the SDK/NDK Tools and OpenJDK sub-modules to your current Unity version.
2. In Unity, switch platform to Android in File > Build Settings and wait for the asset reimport.
3. Open Player Settings and configure your company name, product name, and package name before doing anything else.
4. Enable USB Debugging on a physical Android device and confirm it appears in Unity's Run Device dropdown.
5. Build and run an APK to your device to confirm the setup is working before changing anything else.

Learning Roadmap

1. Get a basic APK running on a physical device before worrying about Play Store requirements or release builds.
2. Revisit the Mobile Optimization guide from this series before building your release candidate — performance issues that are invisible on a PC become obvious on mid-range Android hardware.
3. Set up the keystore and do a test IL2CPP release build locally before the day you need to submit to the Play Store. IL2CPP build errors are not something you want to debug under deadline pressure.
4. Read Google's current target API level requirements before any Play Store submission, since these update annually.

Next Topics To Learn

• Unity Mobile Optimization Guide — performance tuning for Android hardware before you build your release candidate.
• Git and GitHub for Beginners — version control for your project, including keeping the keystore out of public repositories.
• VS Code Setup for Unity Developers — configure your code editor for the C# scripting behind the build you just set up.