Building an APK locally with Expo gives you greater control over your development workflow, allowing you to generate a standalone Android package without depending on Expo’s cloud build services.
This approach is particularly valuable for developers who need faster iteration, offline capabilities, or want to customize their build process.
In this blog, we’ll walk you through the steps to build an APK locally using Expo, highlight the tools you'll need, and cover potential challenges you might face along the way.
Prerequisites
Before you begin, ensure you have the following installed:
Step 1: Initialise an Expo project
If you don’t already have an Expo project, create one with the following command:
Step 2: Configure Expo for bare workflow
By default, Expo manages builds in the cloud, but to generate an APK locally, we need to prebuild our project:
This command converts your managed Expo project into a bare React Native project with the necessary Android and iOS folders.
Step 3: Open the project in Android studio
Step 4: Build the APK using Gradle
To build an APK, use the following command inside the android directory:
This process might take a few minutes. Once completed, your APK will be located in:
android/app/build/outputs/apk/release/app-release.apk
Step 5: Signing the APK (optional)
For distribution, you should sign your APK. Generate a keystore using:
Move the generated keystore to android/app/ and update the android/app/build.gradle file to reference your signing details.
Step 6: Install and test the APK
Once the APK is built, install it on an Android device or emulator:
You can now run and test your Expo-built Android application locally!
Alternative method: building APK locally with EAS build
EAS Build is available to anyone with an Expo account, regardless of whether you pay for EAS or use their Free plan. You can sign up at https://expo.dev/signup.
Expo also provides EAS Build (Expo Application Services), which allows you to build APKs locally without manually handling Gradle commands. Here’s how:
1. Install EAS CLI (if not installed already):
2. Configure EAS for local builds:
3. Run a local build:
Alternatively, you can use --platform all option to build for Android and iOS at the same time:
4. This command will build the APK on your local machine.
5. Find the generated APK:
Why use EAS build locally?
If you are already signed in to an Expo account using Expo CLI, you can skip the steps described in this section. If you are not, run the following command to log in:
You can check whether you are logged in by running
Configure the project
To configure an Android or an iOS project for EAS Build, run the following command:
Expo APK local build: The challenges I faced & how I solved them
While building an APK locally with Expo, you might encounter various challenges. Here are some common issues and how to resolve them:
1. Gradle version issues
Problem: The Build fails due to incompatible Gradle versions.
Solution: Update your Gradle version in android/gradle/wrapper/gradle-wrapper.properties.
Find this line:
distributionUrl=https\://services.gradle.org/distributions/gradle-x.x.x-all.zip
Update it to the latest stable version. You can find the latest version here.
Example:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-all.zip
Update Gradle Plugin (If Needed) android/build.gradle
find classpath 'com.android.tools.build:gradle:x.x.x'
Update it to the latest version found in Android Gradle Plugin release notes.
Ensure your Android SDK is current.
2. Java version mismatch
Problem: Gradle build fails due to incompatible Java versions.
Solution: Ensure you are using the correct Java version (usually Java 11 or Java 17) by setting it in your environment variables.
Open a terminal or command prompt and run: java -version
If the version is not Java 11 or Java 17, you need to update it.
Install the Correct Java Version
Windows: Download & install Java from Adoptium or Oracle.
Mac/Linux: Use Homebrew (Mac) or SDKMAN (Linux) to install:
macOS/Linux
Open the Terminal and edit your shell config:
Add this
Apply changes:
Verify the version:
Set Java Version in gradle.properties
3. Dependency conflicts
Problem: Errors related to conflicting dependencies in package.json.
Solution: Run expo doctor to identify issues and resolve conflicts by upgrading/downgrading dependencies as needed.
4. Missing Android SDK or emulator issues
Problem: The build process cannot locate the required Android SDK.
Solution: Install and configure the Android SDK in Android Studio and set ANDROID_HOME and ANDROID_SDK_ROOT environment variables.
5. Build fails with Hermes
Problem: The app crashes or doesn't build due to the Hermes engine.
Solution: Try disabling Hermes by modifying android/app/build.gradle or ensure you are using a compatible Hermes version.
Check if Hermes is enabled
Open:
Find this block:
If enableHermes: true, try switching it to false and rebuilding.
6. Slow build times
Problem: Gradle takes too long to compile the project.
Solution: Enable Gradle caching and daemon mode, and use a more powerful machine for faster builds.
Enable gradle daemon & caching
1. Open:
(If it doesn’t exist, create it.)
2. Add or modify these lines:
3. Enable build caching
4. Enable parallel execution
5. Configures projects on demand
6. Limits worker processes (adjust based on CPU)
Use a faster gradle distribution
1. Open
2. Update to the latest Gradle version (check Gradle Releases):
Allocate more RAM to gradle
1. Open
2. Add
Use incremental compilation
1. Open
2. Add this inside the android block:
Conclusion
Building APKs locally with Expo gives you complete control over your app’s build process, making it an excellent choice for offline development, thorough debugging, and distributing apps without depending on cloud-based services. This approach can be especially helpful when working in secure environments or when faster iteration cycles are needed.
However, it’s important to be prepared for some common hurdles along the way, such as Gradle version mismatches, dependency conflicts, or issues related to Android SDK configuration.
By identifying and addressing these challenges early, you can create a more reliable and streamlined build workflow.
With the right tools, attention to detail, and a clear understanding of the process, you can confidently build, test, and distribute your Expo-based Android applications entirely on your local machine.
Happy coding!