Can I develop Capacitor apps on Linux?

Yes. Linux is a first-class environment for the web layer and for Android. You install Node or Bun, a JDK, the Android SDK and optionally Android Studio. The only thing Linux cannot do locally is compile and sign the iOS app, because Xcode only runs on macOS. Capgo Build handles iOS builds in the cloud from a Linux machine.

Do I need Android Studio on Linux to build a Capacitor app?

No. The Android command line tools (sdkmanager, platform-tools, build-tools) plus a JDK are enough to run cap sync, Gradle builds and the emulator. Android Studio is useful for the visual debugger, profiler and emulator manager, but it is optional.

Can I build an iOS app from Linux?

You cannot run Xcode on Linux, so you cannot compile or sign iOS locally. You can generate the ios/ project with Capacitor, sync your web assets into it, and send it to Capgo Build, which compiles and signs it on macOS hardware and can submit it to TestFlight.

Why does the Android emulator run slowly on Linux?

The emulator needs hardware acceleration through KVM. Check that virtualization is enabled in your BIOS, install the KVM packages, and add your user to the kvm group. Without KVM the emulator falls back to software rendering and is unusable.

Sviluppo con Capacitor su Linux: la guida completa al setup

Linux è un'ottima piattaforma per il lavoro con Capacitor. Il web layer è puro tooling Node, gli strumenti Android girano nativamente e l'emulatore Linux con KVM è spesso più veloce di quello su Windows. L'unico limite è iOS: Xcode esiste solo su macOS, quindi serve un servizio di cloud build per quella parte.

Questa guida ti accompagnerà in un setup Linux completo, testato su Ubuntu 24.04, Fedora 42 e Arch. Si conclude con una build iOS da Linux utilizzando Build Capgo, così puoi pubblicare su entrambi gli store senza un Mac.

Cosa funziona su Linux e cosa no

Task	Linux
Sviluppo web, Vite, tooling per framework	Sì
`cap add android`, `cap sync`, build Gradle	Sì
emulatore Android	Sì, con KVM
Dispositivo Android fisico via USB	Sì, con le regole udev
Remote debugging con Chrome DevTools	Sì
`cap add ios`, `cap sync ios` (genera e copia)	Sì, con l'avviso che CocoaPods viene saltato
Compila, firma e archivia iOS	No, serve macOS. Usa Capgo Build
Simulatore iOS	No
Safari Web Inspector per iOS WebView	No

Tutto quello che c'è nelle righe “No” passa al cloud o su un iPhone reale con TestFlight. Ne parliamo alla fine.

1) Installa Node o Bun

Il CLI di Capacitor richiede Node 20 o superiore. Bun funge da runtime e package manager ed è più veloce negli install.

# Bun (recommended)
curl -fsSL https://bun.sh/install | bash

# Or Node via your package manager
# Ubuntu / Debian
sudo apt install -y nodejs npm
# Fedora
sudo dnf install -y nodejs
# Arch
sudo pacman -S nodejs npm

Controlla le versioni:

bun --version
node --version

2) Installa un JDK

Capacitor 7 e 8 richiedono JDK 21. I pacchetti della distribuzione vanno bene.

# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk

# Fedora
sudo dnf install -y java-21-openjdk-devel

# Arch
sudo pacman -S jdk21-openjdk

Imposta JAVA_HOME nella ~/.bashrc o ~/.zshrc. Il percorso dipende dalla distribuzione:

# Ubuntu / Debian
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# Fedora
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# Arch
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk

Se hai più di un JDK installato, Gradle sceglierà quello a cui JAVA_HOME punta. Una versione errata apparirà come Unsupported class file major version durante cap run android.

3) Installa l'SDK per Android

Hai due opzioni. Android Studio ti offre gli strumenti GUI. I soli command line tools sono più leggeri e sufficienti per il build.

Opzione A: Android Studio

Scarica il tarball per Linux dal sito di Android Studio ed estrailo:

sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh

Al primo avvio, la configurazione installa il SDK in ~/Android/Sdk.

in Capacitor cap open android deve sapere dove si trova Studio:

export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh

Opzione B: Solo command line tools

mkdir -p ~/Android/Sdk/cmdline-tools
cd ~/Android/Sdk/cmdline-tools
# Download "Command line tools only" for Linux from the Android developer site, then:
unzip commandlinetools-linux-*.zip
mv cmdline-tools latest

Aggiungi il SDK al tuo profilo shell:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Installa ciò che serve a Capacitor e accetta le licenze:

sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses

Abbina la versione della piattaforma al compileSdkVersion nel tuo file generato android/variables.gradle. Capacitor 8 usa 36; Capacitor 7 usa 35.

4) Abilita KVM per l'emulatore

Senza KVM l'emulatore è inutilizzabile. Verifica che la tua CPU supporti la virtualizzazione:

egrep -c '(vmx|svm)' /proc/cpuinfo

Un risultato superiore a 0 indica che è supportata. Installa KVM e dai l'accesso al tuo utente:

# Ubuntu / Debian
sudo apt install -y qemu-kvm
# Fedora
sudo dnf install -y qemu-kvm
# Arch
sudo pacman -S qemu-base

sudo usermod -aG kvm $USER

Effettua il logout e rientra. Crea e avvia un dispositivo:

sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd -n pixel8 -k "system-images;android-36;google_apis;x86_64" -d pixel_8
emulator -avd pixel8

Se l'emulatore segnala problemi di /dev/kvm permessi, la modifica del gruppo non è ancora stata applicata. Riavvia.

5) Accesso USB per i dispositivi fisici

Linux non permette agli utenti standard di comunicare con i dispositivi USB di default. Aggiungi una regola udev:

sudo tee /etc/udev/rules.d/51-android.rules > /dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="2a70", MODE="0666", GROUP="plugdev"
EOF
sudo udevadm control --reload-rules
sudo usermod -aG plugdev $USER

I vendor ID sopra includono Google, Samsung e OnePlus. Trova il tuo con lsusb se il tuo telefono non è in lista. Abilita il debug USB sul telefono, collegalo, accetta il prompt del fingerprint, poi:

adb devices

6) Crea il progetto Capacitor

bun create vite@latest my-app
cd my-app
bun install
bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios

cap add ios su Linux stampa un avviso che CocoaPods non è disponibile. È normale. La ios/ cartella viene comunque creata ed è ciò che Capgo Build compila in seguito.

Esegui sull'emulatore o sul dispositivo:

bunx cap run android

Debugga la WebView in Chrome su chrome://inspect.

7) Release build su Linux

Le release build per Android sono totalmente locali. Genera un keystore con il JDK keytool:

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release

Then build:

cd android
./gradlew bundleRelease

L'AAB si trova in android/app/build/outputs/bundle/release/. Se preferisci non tenere le chiavi di firma sul laptop, Capgo Build per Android salva il keystore una sola volta e compila in cloud usando lo stesso CLI che usi per iOS.

8) iOS da Linux con Capgo Build

Questo è il passaggio che Linux non può gestire da solo. Il workflow:

Builda i tuoi asset web e sincronizzali in ios/.
Salva le tue credenziali di firma iOS una sola volta.
Richiedi un cloud build. Capgo compila, firma e può fare l'upload su TestFlight.

bun run build
bunx cap sync ios

bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

build init ti guida tra le credenziali. Su Linux crei manualmente la chiave API di App Store Connect nel portale Apple; il Guida build iOS mostra ogni passaggio. Per il certificato di distribuzione non serve Keychain Access: genera il CSR e .p12 con OpenSSL come descritto in Certificati iOS e provisioning profile spiegati, o usa il generatore di certificati iOS.

I log scorrono in tempo reale nel terminale. Il flusso completo da Linux a TestFlight è dettagliato in Crea un'app iOS da Linux con Capacitor e Capgo Build.

9) Salta i Native Build con Live Update

Una volta che le shell native sono sugli store, la maggior parte dei cambiamenti quotidiani riguarda JS, HTML e CSS. Puoi inviarli da Linux in pochi secondi con Live Updates di Capgo:

bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production

Riserva i Native Build per modifiche ai plugin, ai permessi e agli upgrade di Capacitor.

Problemi comuni su Linux

SDK location not found: ANDROID_HOME non è esportata nella shell che esegue Gradle. Aggiungila al profilo e apri un nuovo terminale, oppure crea android/local.properties con sdk.dir=/home/you/Android/Sdk.
Unsupported class file major version: JDK errato. Punta JAVA_HOME a JDK 21.
Emulatore con schermo nero o molto lento: KVM non è attivo. Controlla ls -l /dev/kvm e l'appartenenza al tuo gruppo.
adb devices mostra no permissions: regola udev mancante o non ricaricata. Scollega e ricollega dopo il reload.
Gradle daemon esaurisce la memoria: aggiungi org.gradle.jvmargs=-Xmx4g a android/gradle.properties.
Glitch di Wayland e Android Studio: avvia Studio con _JAVA_AWT_WM_NONREPARENTING=1 se le finestre rimangono vuote.

Riassunto

Linux gestisce nativamente l'intero loop Capacitor per Android e il web layer, spesso più velocemente di altri desktop. Per iOS, genera il progetto localmente, sincronizza gli asset e lascia che Capgo Build gestisca la parte macOS. Abbinalo a Live Updates e l'unica volta che penserai a Xcode sarà quando Apple cambierà la sua SDK minima.