Come installare Maven su Ubuntu passo dopo passo

Su Ubuntu, Maven non si installa bene se prima non chiarisci un punto: la JVM deve essere già disponibile e coerente con il progetto che andrai a compilare. Maven è solo il motore di build; senza Java funziona a metà o non parte affatto. La scelta giusta, nella maggior parte dei casi, è installarlo dai repository di Ubuntu per avere integrazione semplice con gli aggiornamenti. Se ti serve una versione specifica, o vuoi allinearti a un ambiente di CI, allora conviene passare all’installazione manuale. In questo articolo vedi entrambe le strade, con i controlli necessari per evitare il classico errore “mvn: command not found” o, peggio, una JVM sbagliata rispetto al progetto.

Verifica preliminare di Java su Ubuntu

Prima di toccare Maven, verifica che Java sia installato e che la versione sia compatibile con ciò che devi compilare. Per molti progetti moderni basta una OpenJDK recente, ma non dare per scontato che il sistema abbia già il runtime corretto. Su macchine fresche, soprattutto server minimal, Java spesso non c’è proprio.

Controlla lo stato attuale con questi comandi:

java -version
javac -version
update-alternatives --config java

Se il primo comando risponde con una versione OpenJDK, sei già a buon punto. Se invece ottieni un errore del tipo command not found, installa una JDK prima di procedere. In ambiente Ubuntu, la scelta più comune è OpenJDK 17 o 21, a seconda del progetto. Per non complicarti la vita, usa il pacchetto della distro salvo vincoli specifici.

Installare Maven dai repository Ubuntu

Questa è la via più semplice e più pulita per la maggior parte dei casi: installi Maven con APT, ti ritrovi il binario nel PATH e ricevi aggiornamenti tramite il normale ciclo del sistema. È la soluzione giusta per workstation, server di build non vincolati a una release precisa e ambienti in cui conta più la manutenzione che l’ultima versione upstream.

Aggiorna l’indice dei pacchetti e installa Maven:

sudo apt update
sudo apt install maven

Al termine, verifica che il comando sia disponibile e che punti alla versione attesa:

mvn -version

L’output deve mostrare almeno tre informazioni utili: versione di Maven, versione della JVM usata e percorso di installazione. Se la versione di Java non è quella attesa, il problema non è Maven: è il sistema di alternative o la variabile JAVA_HOME. In quel caso correggi prima la JVM, poi rilancia il controllo.

Su Ubuntu, il pacchetto APT tende a installare tutto sotto i percorsi standard della distribuzione, di solito con il binario in /usr/bin/mvn e i file applicativi sotto /usr/share/maven. Questo è utile perché non devi gestire manualmente symlink o variabili ambientali per l’uso base.

Installare anche una JDK se manca

Se il sistema non ha Java, installa una JDK completa. Non basta un runtime se devi compilare progetti Java: Maven invoca spesso il compilatore e dipende da strumenti presenti solo nella JDK. Questo passaggio è spesso quello che evita i problemi più banali durante il primo build.

Per una configurazione comune su Ubuntu:

sudo apt update
sudo apt install default-jdk

Dopo l’installazione, verifica di nuovo:

java -version
javac -version

Se vuoi una versione precisa, ad esempio per allinearti a un’applicazione che richiede Java 17, puoi installare il pacchetto specifico disponibile nella tua release di Ubuntu, sempre verificando prima che sia presente nei repository. La regola pratica è semplice: la versione della JDK deve combaciare con i requisiti del progetto, non con le abitudini del server.

Quando conviene installare Maven manualmente

Il pacchetto della distribuzione non è sempre sufficiente. Se devi usare una versione più recente di quella disponibile su Ubuntu, se lavori su un progetto con vincoli ripetibili in CI, o se vuoi mantenere più versioni affiancate, l’installazione manuale è più adatta. In questo scenario rinunci alla comodità degli aggiornamenti APT, ma guadagni controllo.

Il flusso corretto è: scaricare l’archivio ufficiale, verificare l’integrità, estrarre in una directory stabile e impostare il PATH in modo esplicito. Non spargere file in posizioni casuali: quando Maven va aggiornato, devi sapere esattamente dove si trova.

Esempio di installazione manuale in /opt:

cd /tmp
wget https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz
sudo mkdir -p /opt/maven
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/maven --strip-components=1

In questo esempio la versione è indicativa: va sostituita con quella che ti serve davvero. Se hai bisogno di un controllo più rigoroso, aggiungi la verifica della firma o dell’hash del file scaricato. È un passaggio sensato quando il pacchetto viene usato su sistemi esposti o in ambienti dove la supply chain è un tema serio.

Per esporre Maven al sistema, crea uno snippet di configurazione della shell, ad esempio in /etc/profile.d/maven.sh o nel profilo dell’utente dedicato:

export M2_HOME=/opt/maven
export MAVEN_HOME=/opt/maven
export PATH=$M2_HOME/bin:$PATH

Dopo aver ricaricato la shell, controlla ancora una volta:

source ~/.bashrc
mvn -version

Impostare JAVA_HOME in modo corretto

Molti problemi apparentemente legati a Maven sono in realtà problemi di JAVA_HOME. Alcuni progetti, plugin o script di build si aspettano questa variabile valorizzata. Se manca, il comportamento può essere incoerente tra terminali, utenti e processi di CI.

Trova il percorso della JDK installata con:

readlink -f /usr/bin/java

Su Ubuntu, il percorso reale della JDK è spesso sotto /usr/lib/jvm/. Un esempio di configurazione per una shell utente è questo:

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

Se vuoi renderlo persistente solo per l’utente corrente, aggiungi le righe in ~/.bashrc o ~/.profile. Se invece stai configurando un server di build condiviso, valuta un file in /etc/profile.d/ o una configurazione dedicata al servizio systemd che esegue la build. Evita di lasciare variabili ambientali “fantasma” sparse in più file: quando qualcosa non torna, diventa difficile capire quale valore venga davvero usato.

Verifica funzionale con un progetto reale

Il test serio non è solo mvn -version. Devi far eseguire a Maven un’operazione reale, anche minima. Il modo più semplice è creare un progetto di prova o usare uno già presente. Se il comando parte ma la build fallisce subito, hai almeno isolato il problema dal livello di installazione a quello di progetto.

Per una verifica rapida, puoi lanciare una build standard in una directory che contenga un pom.xml valido:

mvn clean test

Se il progetto non esiste ancora, puoi generarne uno base con archetype, ma in molti contesti basta confermare che Maven riesca a risolvere dipendenze e plugin. Se la rete del server è filtrata, il problema può emergere qui e non durante l’installazione. In quel caso controlla proxy, DNS, repository aziendali e policy firewall.

Errori comuni e lettura rapida della causa

Alcuni errori ricorrono spesso e conviene riconoscerli al volo. Se mvn non viene trovato, il problema è nel PATH o nell’installazione. Se Maven parte ma segnala una Java non supportata, il problema è nella JDK. Se la build si blocca scaricando dipendenze, la causa è quasi sempre fuori dal binario: rete, proxy, repository o certificati.

Le verifiche utili sono queste:

• mvn -version: conferma che il binario esiste e mostra la JVM usata.
• echo $PATH: verifica che la directory di Maven sia davvero nel percorso della shell.
• echo $JAVA_HOME: controlla se la variabile è valorizzata in modo coerente.
• apt policy maven: utile per vedere quale versione offre il repository Ubuntu.

Se usi repository aziendali o proxy HTTP/HTTPS, potresti dover configurare anche ~/.m2/settings.xml. In quel file si definiscono mirror, proxy e credenziali per i repository. Non inserire segreti in chiaro in documentazione o script condivisi: usa variabili d’ambiente protette, secret manager o file con permessi stretti.

Configurazione utile per ambienti di build

Su un server dedicato alle build, Maven non va trattato come un pacchetto qualsiasi. È meglio definire un profilo operativo chiaro: utente non privilegiato, home dedicata, cache locale sotto ~/.m2 e controllo delle dipendenze scaricate. Questo riduce effetti collaterali tra job diversi e rende più leggibile la diagnostica quando una build fallisce.

Se il server ospita più pipeline, conviene separare la cache Maven per progetto o per account di esecuzione, soprattutto quando cambiano versioni di plugin e dipendenze. La directory locale di Maven è di solito ~/.m2/repository: cancellarla a caso non è una strategia, al massimo è un’ultima risorsa quando la cache è corrotta e hai già verificato che il problema non dipenda dal repository remoto.

Per diagnosticare una cache problematica puoi usare:

mvn -U clean test

L’opzione -U forza il refresh degli snapshot e di alcune dipendenze, utile quando sospetti che il client stia usando artefatti vecchi. Non abusarne: in ambiente stabile è meglio risolvere la causa del repository o del mirror, non forzare aggiornamenti a ogni esecuzione.

Disinstallazione o cambio versione senza rompere il sistema

Se hai installato Maven con APT, la rimozione è semplice e reversibile. Se invece lo hai messo manualmente in /opt, la gestione è tua: basta rimuovere la directory e ripulire le variabili di ambiente. Prima di farlo, però, verifica che non ci siano pipeline o utenti che dipendono da quel percorso.

Per il pacchetto Ubuntu:

sudo apt remove maven

Per una versione manuale, il rollback è concettualmente più semplice ma va fatto con attenzione: togli il symlink o aggiorna il profilo della shell, poi verifica che mvn non punti più alla directory vecchia. Se hai usato uno script in /etc/profile.d/, rimuovilo solo dopo aver confermato che l’alternativa è già operativa.

In pratica, la regola è questa: scegli APT quando vuoi manutenzione semplice e coerenza con Ubuntu; scegli il tarball ufficiale quando la versione conta più dell’integrazione con la distro. In entrambi i casi, il vero controllo finale è sempre lo stesso: mvn -version, una build reale e la conferma che Java sia quella prevista dal progetto.