The development of complex mobile applications is rarely limited to one single project file. As the functionality grows, Android Studio requires a competent modular architecture, where each component is responsible for its task. The question of how to import a module into Android Studio becomes critical when integrating ready-made libraries, connecting third-party SDKs, or dividing code into logical parts for the development team.
Incorrect configuration of the project structure often leads to compilation errors, problems with Gradle and the inability to run the application on an emulator or a real device. In this article, we will analyze in detail all available methods for adding external and internal modules, consider the nuances of file configuration settings.gradle and build.gradle, and also learn how to eliminate typical synchronization errors that both beginners and experienced engineers encounter.
Preparing the environment and types of modules
Before proceeding with direct import, you need to clearly understand what type of module you are dealing with. There are several main categories in the Android ecosystem: application libraries (Android Library), dynamic modules (Dynamic Feature), test modules and simple Java/Kotlin libraries. Choosing the right type affects what permissions and dependencies are available inside the component.
Android Studio automatically detects the project type upon import, but sometimes manual adjustments are required. Make sure that you have the latest version of the development environment installed, as older versions may not process new configuration formats correctly Gradle Kotlin DSL. Also check that the necessary SDK and build tools are available in the package manager.
⚠️ Attention: If you are importing a module from an old project (Eclipse or earlier versions of Android Studio), the folder structure may differ from modern standards.
Android Gradle Plugin. You will need to manually migrate the files to the directorysrc/main.
It is important to prepare the path to the files in advance. Modules are usually stored in archive format .aar or .jar, or are separate directories with source code. Incorrect location of files relative to the project root (root project) is one of the most common causes of failure during the first synchronization.
Always create a backup copy of the project before making large-scale changes to the module structure, as rolling back changes to Gradle configuration files can be difficult.
Import through the creation wizard project
The easiest and most reliable way to add a new component is to use the built-in wizard Android Studio. This method is ideal if you need to create a new module from scratch or import existing source code that is not yet configured as a library. The system will automatically write the necessary paths in the configuration files.
To begin, open your main project and go to the menu File → New → Import Module. In the window that opens, you will be asked to specify the path to the directory containing the source code of the module or project file. The wizard will analyze the contents of the folder and offer configuration options.
- 📂 Select option Import module from existing source codeif you have a folder with a library project.
- 📦 Use Import .JAR/.AAR Packageif you have a compiled library binary file.
- 🔗 Option Import Gradle Project is suitable for modules that already have their own Gradle build files.
- ⚙️ If necessary, change the module name in the field Module nameto match your application's naming standards.
After selecting the code source, click the button Finish. The development environment will begin the process of indexing files and updating dependencies. A window Buildwill appear in the bottom panel, where the synchronization progress Gradleis displayed. If the process completes successfully, the new module will appear in the window Project and will be available for connection to the main application.
Manually adding dependencies to Gradle
In cases where automatic import does not work or you are working with local files, you must manually edit the build configuration files. This gives complete control over how Android Studio external libraries are perceived. The key file here is settings.gradle (or settings.gradle.kts), located in the root of the project.
You need to add a link to the path to your module to this file. The syntax depends on the version of the Gradle plugin, but the general principle remains the same: you register a new module name and specify its physical location on disk. Without this entry, the development environment simply “will not see” the module, even if the files are in the correct folder.
include ':app', ':my_local_module'
project(':my_local_module').projectDir = new File('path/to/my_local_module')
After registering the module in the project settings, you need to declare a dependency in the file build.gradle of the main application (usually a module :app). The block dependenciesis used here, where you indicate the connection type. For local modules, the configuration most often used is implementation project().
⚠️ Attention: Make sure that the path to the module is in
settings.gradleis specified correctly relative to the root directory. Using absolute paths (for exampleC:/Users/...) will make the project unportable to other computers.
If you use Gradle version 8.0 and higher, please note changes in path declaration syntax, as support for the old format may be limited in future updates. Android Gradle Plugin. Always check the official documentation when updating the version of the build tool.
☑️ Checking the module connection
Setting up build.gradle files and version conflicts
One of the most painful problems When importing third-party modules, there is a dependency version conflict. Different modules may require different versions of the same libraries, for example Support Library or AndroidX. Gradle attempts to resolve these conflicts automatically, but this often results in build errors or unpredictable application behavior at runtime.
For version control, it is recommended to use the mechanism dependencyResolutionManagement at the root file build.gradle. This allows you to centrally set the versions of libraries that will be used in all modules of the project, preventing duplication and desynchronization. This approach is especially important in large projects with dozens of modules.
| Dependency type | Configuration | Description |
|---|---|---|
| Compilation | implementation |
Standard dependency, available only internally module. |
| Public API | api |
Makes the dependency available to other modules that depend on the current one. |
| Testing | testImplementation |
Libraries required only for running local tests. |
| UI Tests | androidTestImplementation |
Dependencies for instrumental tests on the device. |
When errors of the form Multiple dex files define or Class not found, check the dependency tree using the command ./gradlew app:dependencies. This utility will show the complete hierarchy of connected libraries and help identify duplicates. Excluding conflicting versions is done through a block exclude inside the dependency declaration.
How to exclude a transive dependency?
Use the syntax: implementation('com.example:lib:1.0') { exclude group: 'com.conflict', module: 'bad-lib' }. This will remove the problematic library from the build graph.
Working with AAR and JAR files
Often developers have to integrate ready-made binaries whose source code is not available. The .aar (Android Archive) format is preferred because it contains not only compiled code, but also resources, manifest and native libraries. The format contains only Java classes and requires additional configuration to work with Android resources. To connect a local file, you need to place it in the directory inside the application module. Then in the file .jar contains only Java classes and requires additional configuration to work with Android resources.
To connect local AAR or JAR file must be placed in the directory libs inside an application module. Then in the file build.gradle you should add a repository flatDirso that Gradle can find files in this folder. Without this step, the builder will simply ignore the presence of files in the directory.
android {
// ... other settings
}
repositories {
flatDir {
dirs 'libs'
}
}
dependencies {
implementation name: 'name_of_your_file_without_extension', ext: 'aar'
}
Remember that when using flatDir you lose the ability to get transitive dependencies that could be declared inside the AAR file itself. If the library depends on other libraries, you will have to manually register them all in your build.gradle. This increases the risk of errors and makes it difficult to maintain the project in the long term.
⚠️ Attention: .jar files do not contain Android resources (layout, drawable). If a library requires resources, using a bare JAR will crash the application when accessing those resources. Always prefer the AAR format.
Troubleshooting synchronization errors and building
Even if all steps are followed correctly, the synchronization process may fail. The most common problem is version mismatch Compile SDK and Target SDK in the main application and the imported module. Android Studio requires the modules to be API compatible to work correctly.
If you see an error Failed to resolve, check your Internet connection and repository settings in the file settings.gradle. Make sure that there are addresses google() and mavenCentral(). Sometimes it helps to clear the Gradle cache through the menu File → Invalidate Caches / Restart, which forces the development environment to re-download all dependency metadata.
In case of errors in compiling code inside the module, check whether access rights and exports are configured correctly. The classes you want to use in the main application must be public (public). Also make sure that packages (package) are imported correctly and there are no class naming conflicts.
90% of errors when importing modules are due to incorrect configuration of settings.gradle files or conflicting dependency versions in build.gradle.
Why does Android Studio not see the added module?
Most often the problem lies in the file settings.gradle. Make sure the line include ':moduleName' is added and the module name matches what you use in the dependencies. Also check that the module folder actually exists in the specified path and contains the file build.gradle.
How to update the version of the imported library?
If this is an external repository, change the version number in the dependency line implementation in the file build.gradle and click Sync Now. For local modules, replace the file .aar in the folder libs with the new version and clean up the project (Build → Clean Project).
Is it possible to import a module from an Eclipse project?
Yes, but conversion will be required. Use the Import Wizard File → New → Import Project and select the Eclipse project folder. Android Studio will prompt you to convert it to Gradle format. Be prepared to manually correct resource paths and dependencies, since the structure of projects varies greatly.
What to do if you receive a "Duplicate class found" error?
This error means that the same library is included twice or two different modules contain classes with with the same full name. Use the dependency report (dependencies) to find the duplicate and exclude it through the block exclude in the Gradle configuration.
Why is the proguard-rules.pro file needed in the module?
This file contains the code obfuscation rules for that particular module. you use a library with native code or specific reflection, you may need to add rules for saving classes (-keep) so that the application does not crash in the release build.