Come installare Basemap su Python in Ubuntu Linux

Basemap su Ubuntu: scegli prima la strada giusta

Basemap è una libreria storica per la cartografia in Python. Su Ubuntu Linux funziona ancora, ma il punto non è “installarla e basta”: va scelto un binario compatibile con la versione di Python presente sul sistema. Il dettaglio che crea più errori è semplice: Basemap non è il tipo di pacchetto da infilare a caso nel Python di sistema e sperare che tutto resti pulito. Se usi una release recente di Ubuntu, con Python 3 aggiornato, conviene lavorare in un ambiente virtuale e pinning dei pacchetti, così riduci collisioni con NumPy, Matplotlib e dipendenze native.

© TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster — https://trgtkls.it — tutti i diritti riservati.

La regola pratica è questa: prima verifichi quale Python stai usando, poi controlli che versione di Basemap sia installabile per quel ramo, infine installi solo nel virtualenv o in un contesto isolato. Se stai mantenendo un server con più progetti, questo approccio evita di rompere librerie condivise e rende il rollback banale: elimini l’ambiente, non tocchi il resto del sistema.

Versioni supportate e vincolo principale

Il vincolo da tenere a mente è la compatibilità con Python e con NumPy. Basemap non è una libreria moderna nel senso stretto del termine, quindi non aspettarti la stessa elasticità di pacchetti più recenti. In pratica, se il tuo Ubuntu porta un Python molto nuovo, la via più affidabile è installare Basemap dentro un virtualenv e lasciare che pip risolva una combinazione coerente di dipendenze. Se invece devi integrare un’app già esistente, conviene prima leggere la versione corrente di Python e, se necessario, creare un ambiente dedicato con una versione supportata dall’applicazione.

Un errore comune è confondere il pacchetto di sistema con quello Python. I pacchetti APT possono esserci, ma non sempre bastano per l’uso applicativo. La strada più controllabile resta quella standard: installi i prerequisiti di compilazione, crei un ambiente isolato e poi installi Basemap da pip, verificando che il wheel disponibile sia coerente con l’architettura e con la release di Ubuntu.

Prerequisiti di sistema su Ubuntu

Prima di tutto serve il set minimo di strumenti per compilare eventuali estensioni native e per gestire i pacchetti Python in modo pulito. Su una macchina Ubuntu recente, i prerequisiti tipici sono i seguenti:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip \
    build-essential libgeos-dev libgeos-c1v5 \
    pkg-config

Il punto critico è GEOS, perché Basemap dipende da componenti geospaziali che possono richiedere librerie di sistema. Se il pacchetto esatto cambia tra release Ubuntu, il nome del pacchetto può differire leggermente; in quel caso verifica con `apt-cache search geos | grep dev` e scegli il pacchetto di sviluppo corretto per la tua distribuzione. Se il comando non restituisce quello che ti aspetti, non inventare il nome: controlla la release con `lsb_release -a` e chiudi il gap con la ricerca APT.

Installazione consigliata in un virtualenv

La procedura più pulita su Ubuntu è questa: crei un ambiente virtuale, aggiorni gli strumenti di packaging e poi installi Basemap insieme alle dipendenze che usa più spesso. In questo modo isoli il progetto e tieni sotto controllo i conflitti con altri moduli Python presenti sul server.

python3 -m venv ~/venv-basemap
source ~/venv-basemap/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install basemap matplotlib numpy

Se l’installazione va a buon fine, il comando `pip` non deve fermarsi su errori di build o su incompatibilità di versione. In caso di errore, il primo controllo è leggere con attenzione l’ultima parte dell’output: se vedi riferimenti a wheel non disponibile, a compilazione di estensioni o a versioni di NumPy non compatibili, il problema non è Ubuntu in sé ma la combinazione di pacchetti. In quel caso il rollback è semplice: rimuovi il virtualenv e ricrealo con una versione di Python più adatta o con vincoli espliciti sulle dipendenze.

Verifica immediata dopo l’installazione

Dopo l’installazione non fermarti al solo `pip freeze`. La verifica utile è importare il modulo e costruire un oggetto minimo, così intercetti subito problemi di librerie condivise, backend grafico o dipendenze native mancanti.

python -c "from mpl_toolkits.basemap import Basemap; print('Basemap OK')"

Se il messaggio è `Basemap OK`, l’import funziona. Se invece ottieni errori tipo `ImportError`, `DLL load failed` o riferimenti a `libgeos`, devi distinguere tra tre casi: dipendenza di sistema assente, incompatibilità tra NumPy e l’estensione compilata, oppure installazione corrotta nel virtualenv. Per fare una diagnosi rapida, controlla la presenza delle librerie con `ldconfig -p | grep geos` e la versione dei pacchetti Python con `pip show basemap numpy matplotlib`.

Esempio minimo di uso

Una volta installato, il test più semplice è creare una mappa base e salvare un’immagine. Questo non serve solo come demo: è il controllo che dice se l’intera catena funziona, dall’import fino al rendering finale.

python - <<'PY'
from mpl_toolkits.basemap import Basemap
import matplotlib.pyplot as plt

m = Basemap(
    projection='cyl',
    llcrnrlat=-60,
    urcrnrlat=80,
    llcrnrlon=-180,
    urcrnrlon=180,
    resolution='c'
)

m.drawcoastlines()
m.drawcountries()
plt.savefig('basemap-test.png', dpi=150, bbox_inches='tight')
print('Creato basemap-test.png')
PY

Se il file `basemap-test.png` viene creato, il pacchetto è operativo. Se lo script parte ma non salva nulla, controlla i permessi di scrittura nella directory corrente e l’eventuale assenza di backend grafico. Su server headless è normale non avere una GUI: per questo conviene usare `plt.savefig()` e non `plt.show()`.

Problemi tipici su Ubuntu e come chiuderli

Il primo problema reale è la versione di Python. Se il sistema ha Python 3.12 o successivo e Basemap o una sua dipendenza non hanno wheel compatibili, l’installazione può fallire. Il modo corretto per chiudere il gap non è forzare il sistema: crea un virtualenv con una versione di Python supportata dall’app, oppure usa un container dedicato. Prima di cambiare strada, verifica la versione con:

python3 --version
pip --version

Il secondo problema è la presenza di vecchie librerie nel profilo utente. Se hai già installato versioni diverse di Matplotlib o NumPy, l’import di Basemap può pescare moduli incoerenti. La verifica minima è vedere da dove arrivano i moduli:

python - <<'PY'
import numpy, matplotlib
print(numpy.__file__)
print(matplotlib.__file__)
PY

Se i percorsi non sono quelli del virtualenv che ti aspetti, stai usando l’interprete sbagliato. In quel caso la correzione è elementare: riattiva l’ambiente con `source ~/venv-basemap/bin/activate` e riesegui i comandi. Se il problema persiste, controlla se la shell sta usando un alias o se `pip` punta a un Python diverso da `python`.

Il terzo problema è la parte grafica. In ambienti server, l’errore non è quasi mai Basemap in sé ma il backend di Matplotlib. Se stai generando immagini su una macchina senza display, imposta un backend non interattivo prima dell’import di `pyplot`:

python - <<'PY'
import matplotlib
matplotlib.use('Agg')
from mpl_toolkits.basemap import Basemap
import matplotlib.pyplot as plt
print('Backend:', matplotlib.get_backend())
PY

Se il backend risulta `Agg`, sei nella configurazione giusta per un server headless. Se no, chiudi il gap forzando il backend nello script, non a livello di sistema, così limiti l’impatto sugli altri progetti.

Installazione con APT: quando ha senso e quando no

In alcuni casi Ubuntu può offrire pacchetti precompilati tramite APT. È una strada comoda se vuoi una prova rapida o se il progetto è vincolato ai repository della distribuzione. Però il compromesso è evidente: meno controllo sulla versione e maggiore dipendenza dal ciclo di aggiornamento della distro. Per un server applicativo, soprattutto se ospita più stack, il vantaggio del virtualenv resta superiore.

Se vuoi esplorare la disponibilità via repository, la verifica è semplice:

apt-cache search basemap
apt show python3-basemap

Se il pacchetto esiste e la versione è coerente con ciò che ti serve, puoi installarlo con APT. Ma non mischiare a caso APT e pip nello stesso interprete globale: è uno dei modi più veloci per finire in una situazione non riproducibile. Se scegli APT, resta sul pacchetto di sistema; se scegli pip, isola tutto nel virtualenv.

Buone pratiche operative per un server Ubuntu

Su una macchina che fa anche altro, il punto non è soltanto installare Basemap, ma farlo senza introdurre fragilità. Le pratiche minime sono tre: ambiente isolato, dipendenze dichiarate e test ripetibile. Il test ripetibile può essere un piccolo script in repository, così ogni deploy verifica che il rendering funzioni davvero e non solo che i pacchetti siano presenti.

Se il progetto è in produzione, conserva un file di requisiti con versioni pinning, per esempio `requirements.txt`, e non lasciare le installazioni libere. Un esempio sobrio è questo:

basemap==1.4.1
matplotlib==3.8.4
numpy==1.26.4

Le versioni sono un esempio operativo, non un dogma: prima di fissarle, verifica la compatibilità con la tua release Ubuntu e con il Python effettivamente in uso. Se una combinazione non passa i test, non forzarla. Aggiorna in modo coordinato o allinea la versione del runtime, altrimenti stai solo spostando il problema più avanti.

Quando Basemap non è la scelta migliore

Se stai iniziando un progetto nuovo, valuta bene se Basemap è davvero il componente giusto. Per uso nuovo e manutenzione più semplice, spesso conviene orientarsi su librerie più recenti. Basemap resta utile quando hai codice legacy, report già scritti o un ambiente dove riscrivere tutto non ha senso operativo. In altri termini: installarlo su Ubuntu è una cosa, decidere di adottarlo oggi per un nuovo sviluppo è un’altra.

La scelta corretta dipende dal vincolo reale. Se devi mantenere uno script esistente, installi Basemap nel suo ambiente e lo tieni stabile. Se devi progettare una nuova pipeline geospaziale, conviene partire da una soluzione più attuale e con manutenzione più semplice. Questo non cambia la procedura di installazione, ma cambia molto il costo di esercizio nel medio periodo.

Checklist finale rapida

Prima di considerare chiusa l’installazione, controlla questi punti:

• Il comando `python --version` nel virtualenv mostra la versione attesa.
• `python -c "from mpl_toolkits.basemap import Basemap"` termina senza errori.
• Lo script di test produce `basemap-test.png` o un output equivalente.
• Le librerie di sistema richieste, in particolare GEOS, risultano presenti con `ldconfig -p | grep geos`.
• Non stai mescolando pacchetti APT e pip nello stesso interprete globale.

Se uno di questi controlli fallisce, non andare avanti per tentativi casuali. Individua il livello del problema: sistema, ambiente Python, dipendenza nativa o backend grafico. È il modo più veloce per chiudere la causa vera e non solo il sintomo.

In sintesi operativa: su Ubuntu installi Basemap in un virtualenv, con prerequisiti di sistema verificati, test di import eseguito e rendering finale salvato su file. Questa è la combinazione più stabile quando devi lavorare su un server Linux senza sporcare il resto dell’ecosistema Python.