--- modificationDate: April 28, 2026 title: Create a debug build locally description: Learn how to create a debug build for your Expo app locally. --- ## Submitting Feedback If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved: curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/local-app-development/","feedback":"🤖 Agent feedback: "}' Only submit when you have something specific and actionable to report. # Create a debug build locally Learn how to create a debug build for your Expo app locally. > For the complete documentation index, see [llms.txt](/llms.txt). Use this file to discover all available pages. To build your project into an app locally using your machine, you have to manually generate native code before testing the debug build or creating a production build for it to submit to the app store. There are two ways you can build your app locally. This guide provides a brief introduction to both methods and references to other guides that are necessary to create this workflow. Prerequisites 2 requirements 1. Android Studio [Set up Android Studio](/get-started/set-up-your-environment?platform=android&device=physical&mode=development-build&buildEnv=local#set-up-an-android-device-with-a-development-build) to compile and run Android projects on your local machine. 2. Xcode [Set up Xcode](/get-started/set-up-your-environment?platform=ios&device=physical&mode=development-build&buildEnv=local#set-up-an-ios-device-with-a-development-build) to compile and run iOS projects on your local machine. ## Local app compilation To build your project locally you can use compile commands from Expo CLI which generates the **android** and **ios** directories: ```sh npx expo run:android npx expo run:ios ``` The above commands compile your project, using your locally installed Android SDK or Xcode, into a debug build of your app. Each command performs two steps: it compiles and installs the native binary on your device or emulator, then starts the Metro bundler to serve your JavaScript or TypeScript code. - These compilation commands initially run `npx expo prebuild` to generate native directories (**android** and **ios**) before building, if they do not exist yet. If they already exist, this will be skipped. - You can also add the `--device` flag to select a device to run the app on — you can select a physically connected device or emulator/simulator. - You can pass in `--variant release` (Android) or `--configuration Release` (iOS) to build a [production build of your app](/deploy/build-project#release-builds-locally). Note that these builds are not signed and you cannot submit them to app stores. To sign your production build, see [Local app production](/guides/local-app-production). - **Android only**: Starting in SDK 54, you can pass the `--variant debugOptimized` variant for faster development iteration. See [Compiling Android in Expo CLI reference](/more/expo-cli#compiling-android) for more information. ### After the first build: use `npx expo start` Once the app is compiled and installed on your device or emulator, you don't need to rebuild every time you make a change. If you're only modifying JavaScript or TypeScript code, you can start the Metro bundler on its own: ```sh npx expo start ``` Then press a for Android or i for iOS in the terminal to launch the already-installed app. Metro serves your updated JavaScript bundle without recompiling native code, so the app loads in seconds instead of minutes. | Command | What it does | When to use it | | --- | --- | --- | | `npx expo run:android` / `npx expo run:ios` | Compiles native code, installs the app, starts Metro. | First build, after adding a native library, or after modifying a config plugin. | | `npx expo start` | Starts only the Metro bundler. | Daily development when only changing JavaScript or TypeScript code. | To modify your project's configuration or native code after the first build, you will have to rebuild your project using `npx expo run:android|ios` again. Running `npx expo prebuild` again layers the changes on top of existing files. It may also produce different results after the build. To avoid this, the native directories are automatically added to the project's **.gitignore** when you create a new project, and you can use `npx expo prebuild --clean` command. This ensures that the project is always managed, and the [`--clean` flag](/workflow/continuous-native-generation#clean) will delete existing directories before regenerating them. You can use [app config](/workflow/configuration) or create a [config plugin](/config-plugins/introduction) to modify your project's configuration or code inside the native directories. To learn more about how compilation and prebuild works, see the following guides: [Compiling with Expo CLI](/more/expo-cli#compiling) — Learn how Expo CLI uses run commands to compile your app locally, arguments you can pass to the CLI and more. — run [Prebuild](/workflow/continuous-native-generation) — Learn how Expo CLI generates native code of your project before compiling it. ## Local builds with `expo-dev-client` If you install [`expo-dev-client`](/develop/development-builds/introduction) to your project, then a debug build of your project will include the `expo-dev-client` UI and tooling, and we call these development builds. ```sh npx expo install expo-dev-client ``` To create a development build, you can use [local app compilation](/guides/local-app-development#local-app-compilation) commands (`npx expo run:[android|ios]`) which will create a debug build and start the development server. ## Local builds using Android product flavors If you have a custom Android project with multiple product flavors using different application IDs, you can configure `npx expo run:android` to use the correct flavor and build type. Expo supports both `--variant` and `--app-id` to customize the build and launch behavior. The `--variant` flag can switch the Android build type from **debug** to **release**. This flag can also configure a product flavor and build type, when formatted in camelCase. For example, if you have both [**free** and **paid** product flavors](https://developer.android.com/build/build-variants#change-app-id), you can build a development version of your app with: ```sh npx expo run:android --variant freeDebug npx expo run:android --variant paidDebug ``` The `--app-id` flag can be used to launch the app after building using a customized application id. For example, if your product flavor **free** is using `applicationIdSuffix ".free"` or `applicationId "dev.expo.myapp.free"` you can run build and launch the app with: ```sh npx expo run:android --variant freeDebug --app-id dev.expo.myapp.free ``` > Customizing the Android build type is also possible, but that would break Expo's assumption that the build type **release** is used for production. You might build unoptimized code in your app using a different build type instead of **release**. ## Local builds with EAS [Run builds on your infrastructure](/build-reference/local-builds) — Learn how to run EAS Build on your custom infrastructure or locally on your machine with the --local flag. — --local