Come installare OpenCV per Python su Ubuntu in modo semplice

Su Ubuntu, il modo più pulito per usare OpenCV con Python dipende da quello che devi farci davvero: sviluppo rapido, progetto in venv, integrazione in un sistema già in produzione, oppure build personalizzata con supporto a moduli extra. Nella maggior parte dei casi non serve compilare nulla: il pacchetto Python di OpenCV installato via pip dentro un ambiente virtuale è sufficiente, più facile da riprodurre e più semplice da rimuovere.

Il punto chiave è evitare la confusione tra i pacchetti di sistema e quelli Python. apt installa librerie e binding pensati per il sistema operativo, mentre pip gestisce il pacchetto Python nel tuo ambiente. Mischiare i due livelli senza criterio porta quasi sempre a versioni incoerenti, moduli mancanti o import che sembrano funzionare oggi e saltano dopo un aggiornamento.

Scelta pratica: pacchetto Python via pip o librerie di sistema

Se devi usare OpenCV in uno script Python, la strada consigliata è questa: crea un ambiente virtuale, aggiorna gli strumenti base e installa opencv-python. Se ti servono funzionalità extra, come supporto a codec particolari o moduli aggiuntivi, puoi valutare opencv-contrib-python. Se invece stai costruendo un sistema server con dipendenze controllate a livello OS, potresti preferire i pacchetti Debian/Ubuntu, ma accetti il compromesso di avere meno flessibilità sulle versioni.

In pratica: per sviluppo applicativo e automazione, pip in venv. Per integrazione con stack di sistema e dipendenze native già governate da apt, valuta i pacchetti distribuiti da Ubuntu. Compilare da sorgente ha senso solo quando ti servono opzioni che i pacchetti precompilati non coprono.

Prerequisiti minimi su Ubuntu

Prima di installare OpenCV, conviene portare il sistema a uno stato coerente. I prerequisiti base sono Python 3, pip, il supporto ai virtual environment e, se devi compilare o installare estensioni native, alcuni tool di build. Su Ubuntu recente i nomi dei pacchetti sono stabili e la procedura è lineare.

Esegui questi controlli iniziali:

python3 --version
python3 -m pip --version
python3 -m venv --help

Se uno di questi comandi fallisce, il problema non è OpenCV ma l’ambiente Python di base. In quel caso installa i pacchetti necessari con apt:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

Se prevedi di compilare pacchetti con estensioni native, aggiungi anche gli strumenti di sviluppo:

sudo apt install -y build-essential python3-dev

Per OpenCV installato via wheel Python, questi strumenti non sono sempre indispensabili, ma averli pronti evita blocchi quando una dipendenza richiede compilazione locale.

Installazione consigliata con virtual environment

Questa è la procedura da usare nella maggior parte dei casi. Isola il progetto, riduce il rischio di conflitti e rende il rollback banale: cancelli la directory dell’ambiente e riparti. È il compromesso migliore tra semplicità e controllo.

1. Crea la directory del progetto e l’ambiente virtuale.

mkdir -p ~/progetti/opencv-test
cd ~/progetti/opencv-test
python3 -m venv .venv

2. Attiva l’ambiente.

source .venv/bin/activate

3. Aggiorna gli strumenti di packaging dentro il venv.

python -m pip install --upgrade pip setuptools wheel

4. Installa OpenCV.

python -m pip install opencv-python

Se ti servono i moduli contrib, usa questo pacchetto al posto del precedente:

python -m pip install opencv-contrib-python

Se stai lavorando su un server headless e non ti servono interfacce grafiche, puoi ridurre dipendenze e dimensione installando la variante senza GUI:

python -m pip install opencv-python-headless

La variante headless è spesso la scelta giusta in container, ambienti CI/CD e host senza desktop. Evita dipendenze inutili su X11 o librerie grafiche che non userai mai.

Verifica immediata dell’installazione

Dopo l’installazione, non fidarti solo del messaggio di successo di pip. Verifica l’import e controlla la versione effettiva della libreria. È il test minimo che distingue un’installazione corretta da un ambiente apparentemente sano ma incoerente.

python -c "import cv2; print(cv2.__version__)"

Se il comando restituisce una versione, il binding Python funziona. Per una verifica un po’ più concreta, prova a creare una matrice e a leggere una proprietà base:

python - <<'PY'
import cv2
import numpy as np
img = np.zeros((100, 100, 3), dtype=np.uint8)
print(cv2.__version__)
print(img.shape)
PY

Se questo script si esegue senza errori, hai confermato che Python, NumPy e OpenCV convivono correttamente nello stesso ambiente.

Dipendenze di sistema che contano davvero

OpenCV via wheel Python porta con sé molte dipendenze, ma non tutte le situazioni sono uguali. Su Ubuntu server minimale, o in container molto snelli, può mancare qualche libreria runtime utile per leggere formati immagine o video. In quel caso il sintomo tipico non è l’errore di installazione, ma un fallimento a runtime quando provi a usare una funzione specifica.

Se devi leggere immagini JPEG, PNG o gestire video in modo più completo, può essere utile installare alcune librerie di sistema comuni:

sudo apt install -y libgl1 libglib2.0-0

In molti contesti server, soprattutto se usi opencv-python-headless, queste dipendenze sono sufficienti. Se invece compaiono errori su codec o backend video, il problema va isolato per funzione: non si aggiungono pacchetti a caso, si verifica prima quale backend sta fallendo.

Un controllo utile è vedere quale modulo Python stai importando davvero:

python - <<'PY'
import cv2
print(cv2.__file__)
PY

Se il path non punta al tuo .venv, stai usando un interprete diverso da quello previsto. È uno degli errori più comuni quando si lavora con più versioni di Python o si lancia lo script da editor e non da shell attiva nell’ambiente corretto.

Quando usare i pacchetti Ubuntu

Ubuntu offre anche pacchetti OpenCV nei repository, ma la scelta va fatta con criterio. Il vantaggio è l’integrazione con il sistema e la gestione centralizzata degli aggiornamenti. Lo svantaggio è che la versione può essere più vecchia e i binding Python non sempre seguono il ritmo delle release upstream.

Se vuoi verificare cosa mette a disposizione la tua release, puoi cercare i pacchetti disponibili:

apt-cache search opencv | sort

Per esempio, potresti trovare librerie come libopencv-dev o pacchetti Python correlati. In questo scenario, conviene installare solo ciò che serve davvero. Se il requisito è compilare software C++ che linka contro OpenCV, allora i pacchetti di sistema hanno senso. Se il requisito è uno script Python, il percorso con venv resta più pulito.

Un errore frequente è installare sia il pacchetto di sistema sia quello Python via pip, poi aspettarsi che usino la stessa versione e gli stessi backend. Non è una buona idea se non hai una ragione precisa e un controllo stretto della catena di esecuzione.

Installazione con supporto extra: contrib, GUI e video

OpenCV non è solo cv2.imread() e cv2.imwrite(). Se ti servono algoritmi aggiuntivi, feature detector particolari, tracking o moduli sperimentali, il pacchetto opencv-contrib-python è quello da considerare. La differenza pratica sta nei moduli inclusi, non nella sintassi di base dell’uso.

Per progetti desktop che aprono finestre e mostrano immagini, la versione standard va bene. Se però stai distribuendo su macchine senza sessione grafica, la presenza di componenti GUI crea solo rumore. In quel caso, la variante headless evita dipendenze non necessarie e riduce il rischio di errori del tipo “cannot open display”.

Per il video, il discorso è simile: leggere una webcam o un file MP4 dipende anche dai backend disponibili nel sistema. Se un test con cv2.VideoCapture() fallisce, la domanda giusta non è “OpenCV è installato?”, ma “quale backend sto usando e quali librerie runtime mancano?”.

Snippet minimo di uso in Python

Dopo l’installazione, un test reale dovrebbe fare almeno una lettura immagine e una trasformazione banale. Questo ti dice subito se il binding funziona e se NumPy è allineato con OpenCV.

python - <<'PY'
import cv2

img = cv2.imread('test.jpg')
if img is None:
    raise SystemExit('Immagine non letta: file mancante o formato non supportato')

gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print('OK', gray.shape)
PY

Se il file non viene letto, il problema potrebbe essere banale: percorso sbagliato, permessi, file corrotto o formato non supportato dal backend presente. È utile distinguere subito il problema di installazione da quello dei dati in ingresso.

Compilare OpenCV da sorgente: solo se hai un motivo

La compilazione da sorgente non è la via normale per un articolo “semplice”, ma in alcuni ambienti è l’unica strada sensata. Succede quando servono patch specifiche, ottimizzazioni CPU particolari, moduli disabilitati o abilitati in modo selettivo, oppure integrazione con librerie che i pacchetti precompilati non includono.

Il costo operativo però è reale: più dipendenze, più tempo, più probabilità di introdurre differenze tra ambienti. Se devi solo eseguire script Python, fermati prima della build manuale. Se invece hai un requisito tecnico chiaro, allora la compilazione può essere giustificata.

Una build tipica richiede almeno strumenti di compilazione, CMake, librerie di sviluppo e repository sorgente. Su Ubuntu il flusso generale è questo:

sudo apt update
sudo apt install -y build-essential cmake git pkg-config python3-dev python3-numpy

Da lì in poi la procedura dipende da cosa vuoi abilitare. A quel punto serve leggere la documentazione del progetto o i flag della tua pipeline di build, perché non ha senso copiare una ricetta generica e sperare che coincida con il tuo caso.

Errori tipici e come leggerli

Se ottieni ModuleNotFoundError: No module named 'cv2', il problema è quasi sempre uno di ambiente: OpenCV non è installato in quell’interprete, oppure stai eseguendo lo script con un Python diverso da quello in cui hai fatto pip install. La verifica più rapida è confrontare which python e python -m pip --version.

which python
python -m pip --version

Se import cv2 funziona ma la lettura delle immagini fallisce, controlla il file, i permessi e il formato. Se invece il problema è una finestra grafica che non compare, molto spesso stai usando un ambiente headless o un server senza display. In quel caso non va “aggiustato OpenCV” a caso: devi scegliere una variante compatibile con l’uso reale.

Se compare un errore su librerie condivise mancanti, usa ldd sul modulo o sul binario coinvolto per capire quale dipendenza non è risolta. Questa è una diagnosi più utile che installare pacchetti alla cieca.

ldd .venv/lib/python3*/site-packages/cv2/*.so

Il path esatto può cambiare in base alla versione di Python e alla distribuzione del wheel, ma il principio è lo stesso: individua la libreria mancante prima di correggere l’ambiente.

Rollback pulito e manutenzione

Il vantaggio del virtual environment è che il rollback non richiede operazioni invasive. Se un upgrade rompe qualcosa, puoi rimuovere l’ambiente e ricrearlo. È una strategia molto più sicura di un’installazione globale che lascia residui nel sistema.

deactivate
rm -rf .venv

Se hai installato pacchetti a livello sistema con apt, il rollback è ugualmente lineare ma va fatto con più attenzione perché può coinvolgere altri software che dipendono da quelle librerie. Prima di rimuovere, verifica le dipendenze inverse e l’impatto sul resto dello stack.

In sintesi operativa: per Python su Ubuntu, la soluzione più semplice e meno fragile è venv + pip + opencv-python. Passa a opencv-contrib-python solo se ti servono davvero i moduli extra. Usa opencv-python-headless se non hai GUI. Compila da sorgente solo quando hai un requisito tecnico che le wheel non coprono.

Assunzione: Ubuntu recente, Python 3 già disponibile o installabile dai repository ufficiali, e nessun vincolo particolare su versione di OpenCV salvo quelli dichiarati nel progetto.