Tesseract OCR in Python
con pytesseract.
Una guida completa e testata a pytesseract: installazione, API principale, preprocessamento delle immagini, PDF, punteggi di confidenza, configurazione PSM/OEM, prestazioni e gli errori più comuni.
Avvio rapido (tre righe)
Installa prima il motore, poi esegui questo. La configurazione completa segue sotto.
import pytesseract
from PIL import Image
text = pytesseract.image_to_string(Image.open("image.png"))
print(text)Installare pytesseract
pytesseract è solo un wrapper: richiama il binario di Tesseract, quindi il motore va installato prima.
pip install pytesseract pillow
# opzionale, per il preprocessamento:
pip install opencv-python numpy
# opzionale, per input PDF:
pip install pdf2imageSe il motore non è nel PATH (comune su Windows), indicalo esplicitamente:
import pytesseract
pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"Nuovo al motore? Vedi la guida all'installazione per Windows, macOS, Linux, Docker e WSL.
API principale
pytesseract espone una funzione per tipo di output. Scegli quella adatta alle tue esigenze.
| Funzione | Restituisce | Usala quando |
|---|---|---|
image_to_string | Testo semplice | Ti serve solo il testo riconosciuto |
image_to_data | Riquadri + confidenza per parola | Evidenziare testo, filtrare parole poco affidabili |
image_to_boxes | Riquadri per carattere | Geometria a livello di carattere |
image_to_pdf_or_hocr | PDF ricercabile o hOCR | Creare PDF ricercabili o overlay web |
image_to_osd | Rilevamento orientamento e scrittura | Rilevare rotazione o scrittura prima dell'OCR |
image_to_alto_xml | ALTO XML | Pipeline di archiviazione / biblioteche |
Configurazione: PSM, OEM, lingue e whitelist
Passa le opzioni come stringa separata da spazi a config=.
# Un blocco di testo, motore LSTM, italiano
text = pytesseract.image_to_string(img, lang="ita", config="--oem 3 --psm 6")
# Solo cifre (totali di scontrini, letture di contatori)
text = pytesseract.image_to_string(img, config="--psm 7 -c tessedit_char_whitelist=0123456789.")
# Lingue combinate
text = pytesseract.image_to_string(img, lang="eng+ita")| PSM | Modo | Ideale per |
|---|---|---|
| 3 | Completamente automatico (predefinito) | Documenti standard |
| 4 | Una colonna di dimensioni variabili | Articoli, pagine a una colonna |
| 6 | Un blocco di testo uniforme | Paragrafi, etichette |
| 7 | Una singola riga di testo | Didascalie su una riga, campi isolati |
| 8 | Una singola parola | Parole singole |
| 11 | Testo sparso | Scontrini, testo di interfaccia sparso |
| 13 | Riga grezza | Una riga senza espedienti Tesseract |
Modi OEM: --oem 1 (solo LSTM, predefinito in v5), --oem 0 (legacy), --oem 3 (auto). Riferimento completo nella documentazione.
Preprocessamento delle immagini
Un input pulito è il fattore più importante per la precisione. Questi sono i passaggi che contano di più.
import cv2, numpy as np, pytesseract
from PIL import Image
image = cv2.imread("scontrino.jpg")
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
# Ingrandisci il testo piccolo a ~300 DPI equivalenti
gray = cv2.resize(gray, None, fx=2, fy=2, interpolation=cv2.INTER_CUBIC)
# Riduci il rumore, poi soglia di Otsu in bianco e nero puro
blur = cv2.GaussianBlur(gray, (5, 5), 0)
_, binary = cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
text = pytesseract.image_to_string(Image.fromarray(binary))- Scala di grigi — rimuovi i canali di colore prima della soglia.
- Ingrandimento — il testo sotto ~20 px è riconosciuto male; ingrandiscilo.
- Soglia — Otsu con luce uniforme, adattiva con luce irregolare.
- Riduzione del rumore — una sfocatura leggera rimuove macchie lette come punteggiatura.
- Raddrizzamento — correggi la rotazione con
cv2.minAreaRectprima dell'OCR. - Ritaglio dei bordi — rimuovi i bordi scuri che confondono l'analisi del layout.
Posizioni e punteggi di confidenza
Usa image_to_data per ottenere riquadri per parola e una confidenza da 0 a 100, poi filtra il rumore.
from pytesseract import Output
data = pytesseract.image_to_data(img, output_type=Output.DICT)
for text, conf in zip(data["text"], data["conf"]):
if text.strip() and float(conf) > 60: # scarta il rumore poco affidabile
print(round(float(conf)), text)OCR di un PDF in Python
Tesseract lavora su immagini: rasterizza prima le pagine con pdf2image (che richiede poppler).
import io, pytesseract
from pdf2image import convert_from_path
from pypdf import PdfWriter, PdfReader
pages = convert_from_path("scansione.pdf", dpi=300) # richiede poppler
writer = PdfWriter()
for page in pages:
pdf_bytes = pytesseract.image_to_pdf_or_hocr(page, extension="pdf")
writer.add_page(PdfReader(io.BytesIO(pdf_bytes)).pages[0])
with open("scansione_ricercabile.pdf", "wb") as f:
writer.write(f)Su Windows, passa la cartella bin di poppler con poppler_path=. Per un flusso più completo, vedi la documentazione sui formati di output.
Prestazioni
pytesseract richiama la CLI a ogni chiamata, quindi il throughput dipende da come strutturi il processo.
| Approccio | Quando | Compromesso |
|---|---|---|
pytesseract per chiamata | Script e attività singole | Avvia un processo per chiamata — lento nei cicli |
| Raggruppare in TIFF multipagina | Molte pagine, stesse impostazioni | Un processo per molte pagine |
multiprocessing | Molte immagini indipendenti | Usa tutti i core; più memoria |
tesserocr | Alto volume, in-process | Binding nativo, più configurazione |
Catalogo degli errori
Questi errori coprono la maggior parte dei problemi con pytesseract.
| Errore | Causa | Soluzione |
|---|---|---|
TesseractNotFoundError | Binario non installato o fuori dal PATH | Installa il motore o imposta pytesseract.pytesseract.tesseract_cmd. |
(-215:Assertion failed) src.type() == CV_8UC1 | Soglia su un'immagine a 3 canali | Converti con cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) prima. |
Error opening data file ...fra.traineddata | Pacchetto lingua mancante | Installa la lingua o imposta TESSDATA_PREFIX. |
| Output vuoto | DPI basso, PSM errato o nessun testo | Ingrandisci, prova --psm 6/7/11 e preprocessa. |
| Molto lento nei cicli | Un processo per chiamata | Raggruppa, usa multiprocessing o tesserocr. |
Misurare la precisione
Misura i tassi di errore su caratteri e parole invece di valutare l'output a occhio.
import pytesseract, jiwer
from PIL import Image
hypothesis = pytesseract.image_to_string(Image.open("esempio.png"))
reference = open("esempio.gt.txt").read()
print("CER:", jiwer.cer(reference, hypothesis))
print("WER:", jiwer.wer(reference, hypothesis))Mantieni un piccolo set di immagini rappresentative con il testo di riferimento come test di regressione e rieseguilo quando cambi preprocessamento o configurazione.
FAQ Python
Come uso Tesseract OCR in Python?
Installa prima il motore, poi pip install pytesseract pillow. Apri l'immagine con Pillow e chiama pytesseract.image_to_string(img).
Perché ottengo TesseractNotFoundError?
pytesseract non trova il binario. Installa il motore, mettilo nel PATH o imposta pytesseract.pytesseract.tesseract_cmd con il percorso completo.
Come miglioro la precisione?
Porta a ~300 DPI, scala di grigi, soglia, riduzione del rumore, raddrizzamento e il --psm corretto. Usa il lang= adatto e, per campi fissi, una whitelist di caratteri.
Come faccio l'OCR di un PDF?
Usa pdf2image (con poppler) per convertire le pagine in immagini, esegui pytesseract su ciascuna e combina con image_to_pdf_or_hocr(..., extension="pdf").
Come ottengo i punteggi di confidenza?
Usa image_to_data(..., output_type=Output.DICT) e filtra la lista conf.
pytesseract è lento?
Ogni chiamata avvia un processo. Raggruppa, usa multiprocessing o passa al binding in-process tesserocr per alte prestazioni.
Passi successivi
Approfondisci il motore e l'ecosistema.