Cómo Cambiar el Package Name en Android Studio (XML y Jetpack Compose)

Querer renombrar el paquete de un proyecto en Android Studio es más común de lo que parece. Los motivos pueden ser varios: desde un simple cambio de nombre de la aplicación —donde el package name incluye el nombre de la app— hasta una reestructura completa antes de subirla a producción o publicarla en la Google Play Store. Sea cual sea el caso, hacerlo de forma incorrecta puede inutilizar el proyecto por completo.

La buena noticia es que el proceso es mucho más sencillo de lo que parece, siempre y cuando se sigan los pasos en el orden correcto. A continuación te explico los dos enfoques según el tipo de proyecto: el moderno con Jetpack Compose y el tradicional basado en XML y Vistas.

Enfoque Moderno: Jetpack Compose, Namespace y Application ID

A partir de versiones recientes del Android Gradle Plugin (AGP), Android Studio separó dos conceptos que antes convivían bajo el mismo nombre de paquete:

• namespace: define el paquete interno donde se generan las clases de recursos como R.java y BuildConfig. Es el identificador de tus recursos dentro del código.
• applicationId: es el identificador único de tu aplicación en la Google Play Store y en el dispositivo. Es lo que el sistema operativo y la tienda usan para distinguir tu app de cualquier otra.

Esto tiene una ventaja enorme: ya no es obligatorio que la estructura de carpetas físicas del proyecto coincida con el applicationId. Aunque sigue siendo una buena práctica mantenerlos alineados para evitar confusiones, la separación te da mucha más flexibilidad al renombrar.

Para cambiar el nombre del paquete en un proyecto de Compose, simplemente actualiza estos dos campos en el archivo build.gradle.kts de nivel de módulo (el del directorio app/):

android {
    // El namespace controla dónde se generan tus archivos R y la vinculación interna
    namespace = "net.desarrollolibre.composeapp"

    defaultConfig {
        // El applicationId es lo que ve el usuario y la Play Store
        applicationId = "net.desarrollolibre.composeapp"
        versionCode = 1
        versionName = "1.0"
    }
}

Si el namespace cambió respecto al valor anterior, deberás actualizar todos los imports de tu clase R en los archivos Kotlin que referencian recursos manualmente (por ejemplo, R.string.app_name o R.drawable.ic_launcher). Android Studio detecta estos conflictos automáticamente y te ofrece una corrección rápida con Alt + Enter para resolverlos en todo el proyecto de una sola vez, sin necesidad de hacerlo archivo por archivo.

Finalmente, es imprescindible ejecutar un Clean Project y luego un Rebuild Project desde el menú Build. Esto elimina cualquier rastro del nombre anterior que pueda haber quedado en la caché del compilador y previene errores de compilación inesperados.

Enfoque Legacy: Proyectos Basados en XML y Vistas

Renombrando el paquete en Android Studio (Dolphin y versiones superiores)

En proyectos más antiguos que usan el sistema tradicional de Views y XML, el package name está estrechamente ligado a la estructura de carpetas del proyecto. Por eso, el proceso requiere un par de pasos adicionales. El primero es desactivar una opción del panel de proyecto que, por defecto, oculta la estructura real de los paquetes.

Ve al panel Project, haz clic derecho sobre el icono del engranaje (⚙) y desmarca la opción Compact Middle Packages (en versiones anteriores de Android Studio esta opción se llamaba Compact Empty Middle Packages). Esta opción, cuando está activa, colapsa visualmente los paquetes intermedios vacíos en un solo nodo, lo que impide renombrarlos de forma individual:

Una vez desactivada la opción, la estructura de carpetas se expande y podrás ver cada segmento del paquete por separado. Si tu package name está compuesto por varios segmentos (por ejemplo, com.example.miapp), deberás renombrar cada carpeta de forma individual: haz clic derecho sobre la carpeta del segmento que quieras cambiar, selecciona Refactor y luego Rename.

En el diálogo que aparece, Android Studio te preguntará qué quieres renombrar. Es crítico que elijas la opción Rename package y no solo el directorio. Al hacerlo, el IDE actualiza automáticamente todas las referencias en el AndroidManifest.xml, las declaraciones de paquete al inicio de cada archivo .java o .kt, y cualquier otra referencia interna. Cuando el análisis esté listo, presiona el botón Do Refactor para aplicar todos los cambios:

Con el refactor completado, el último paso es actualizar el applicationId manualmente en el archivo build.gradle.kts (o build.gradle) de nivel de módulo. Este valor no se actualiza automáticamente con el refactor, así que es esencial cambiarlo para que el identificador de la app quede completamente sincronizado:

// build.gradle.kts
android {
    defaultConfig {
        applicationId = "net.desarrollolibre.nueva.app"
        // ...
    }
}

Al igual que con el enfoque moderno, termina siempre con un Clean Project y un Rebuild Project para asegurarte de que la compilación parte desde cero con el nuevo nombre. Si después del rebuild sigues viendo errores relacionados con el paquete anterior, prueba a invalidar las cachés desde File → Invalidate Caches / Restart…